For Affiliates & Partners

Partner API: Errors, Rate Limits & Integration Checklist

The Partner API error contract, rate limit headers, and a step-by-step checklist for going live.

3 min read

Everything you need to handle failures gracefully and confirm you're ready for production traffic.

#Rate Limits

Limits are per account, set at onboarding (defaults: 60 requests/min, 5,000 calls/day). Every response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1751889600

Exceeding a limit returns 429 RATE_LIMITED with error.detail.reason of "rate_limited" (per-minute) or "daily_limit_exceeded". Use X-RateLimit-Reset (a Unix timestamp) to back off intelligently rather than retrying immediately.

#Error Contract

On any error, success is false, data is null, and error carries a stable code, a human-readable message, and a machine-readable detail object. Always branch on error.code / error.detail.reason — never on the message text, which may change without notice.

HTTP	`error.code`	`error.detail.reason`	Meaning	Billed?
401	`UNAUTHORIZED`	`invalid_api_key` \| `key_expired`	Bad/missing credentials — a revoked key reports `invalid_api_key`, indistinguishable from a nonexistent one, by design	No
402	`PAYMENT_REQUIRED`	`monthly_cap_reached`	Standard accounts only: your agreed monthly call ceiling was hit — resumes next billing period, or contact Exlitem to raise it	No
403	`FORBIDDEN`	`account_suspended`	Account disabled — contact Exlitem	No
404	`NOT_FOUND`	—	Unknown expert UUID (or expert no longer active)	No
422	`VALIDATION_ERROR`	—	Bad parameters; `detail` lists field errors	No
429	`RATE_LIMITED`	`rate_limited` \| `daily_limit_exceeded`	Slow down / daily cap reached	No
503	`EXTERNAL_SERVICE_ERROR`	—	Search backend temporarily unavailable — retry with backoff	No

Sample error:

{
  "success": false,
  "data": null,
  "pagination": null,
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Payment required.",
    "detail": { "reason": "monthly_cap_reached", "period_units": 50000, "monthly_hard_cap_units": 50000 }
  }
}

No error response is billed — a failed or rate-limited call never counts against your monthly usage.

#Integration Checklist

Store the secret key server-side; confirm connectivity with GET /ping.
Integrate GET /search with test keys; handle did_you_mean / auto_corrected.
Treat every page fetch and profile fetch as billable — cache responses on your side (≤ 24 h per contract) to avoid re-billing the same view.
Send Idempotency-Key on retries.
Handle 402 (only relevant if your account has a monthly cap — contact Exlitem to raise it), 429 (backoff using X-RateLimit-Reset), and 503 (retry).
Monitor GET /usage if you want visibility into your own call volume ahead of the monthly invoice; there's no balance to watch.
If your account doesn't have the contact_info capability, link end users to https://exlitem.com/experts/{profile_url_slug} for contact, with the agreed "Powered by Exlitem" attribution. If it does, budget for the contact-reveal surcharge on calls that return a real email/phone.
Swap to live keys after Exlitem activates your account.

#Questions

Reach out to your Exlitem account contact, or email [email protected].

All For Affiliates & Partners articles