Errors & status codes
What every Fiber error means, which ones are safe to retry, and whether you were charged.
Errors & status codes
When a call fails, we tell you what happened, whether to retry, and whether it cost anything. This page is the reference for every status the API returns, so your client can handle each one deliberately instead of treating all failures alike.
What an error looks like
Errors come back as JSON with a status code and a readable message:
{
"statusCode": 400,
"error": "Bad Request",
"message": "body/apiKey Required"
}Billing and access denials carry a machine-readable error code you can
branch on (INSUFFICIENT_CREDITS, PLAN_EXPIRED, and the rest below). Every
500 includes a 6-digit error code (in errorCode and in the message);
quote it to support and we can find the exact request.
Two things that are not errors:
- Unknown fields in your request don't fail it. They come back in
warningsso you can spot a typo without breaking a working call. - No match on most lookups is a successful 200 with an empty result. A 404 means the input itself didn't resolve (an unknown list, job, or company).
Status codes
| Status | Code / message | What it means | What to do |
|---|---|---|---|
| 400 | Bad Request | The request body or query is invalid; the message names the field | Fix the request; don't retry as-is |
| 401 | "No API key provided!" | No key in the body, query, or headers | Send your key. See Passing the key |
| 401 | "Invalid or expired authentication token." | An OAuth token (MCP) is invalid or expired | Sign in again |
| 402 | INSUFFICIENT_CREDITS | Your organization's balance can't cover the call | Top up, or turn on auto top-up. See Billing |
| 402 | PLAN_EXPIRED | Your billing period has ended, even if credits remain | Renew your plan or contact us for an extension |
| 403 | "Invalid API key provided!" | The key isn't one we recognize | Check you copied the whole key |
| 403 | "This API key has expired…" | The key passed its expiration date | Extend it, or create a new key |
| 403 | "This API key has been revoked…" | The key was revoked | Create a new key |
| 403 | API_KEY_CREDIT_LIMIT_REACHED | This key reached its own credit limit; the organization may still have credits | Raise, remove, or reset the key's limit. See Per-key credit limits |
| 403 | OPERATION_NOT_PERMITTED | The operation isn't included in your plan | Contact your account manager |
| 403 | "You cannot access this route!" | Your plan doesn't include this product area | Contact your account manager |
| 404 | Varies | The thing you asked for doesn't exist (a list, a job ID, a company we couldn't resolve) | Check the identifier |
| 409 | Varies | Conflicts with existing state (for example, a duplicate) | Read the message; usually no retry |
| 413 | Payload Too Large | The request body is over 5 MB | Split the request |
| 422 | Varies | The request is valid but has nothing we can act on (for example, no usable identifier) | Add a usable input |
| 429 | "Rate limit exceeded. Please try again later." | You're over the endpoint's rate limit | Back off and retry. See Rate limits |
| 500 | "An unexpected server error occurred… error code 483920" | Something failed on our side | Retry once; if it persists, send support the error code |
| 501 | "Sandbox mode is not yet available for this endpoint." | A sandbox key called an operation without sandbox support | Use a live key for that call |
| 503 | Varies | Fiber is temporarily unable to complete the call | Try again shortly |
Tracker calls from an organization whose plan doesn't include Tracker return 403 with "Your current plan does not include Tracker access."
Which errors to retry
- Retry 429 and 503 with backoff, honoring the
Retry-Afterheader when it's present. A 500 is worth one retry. - Don't retry 400, 401, 402, 403, 404, 409, 413, 422, or 501 until you've changed something; the same request returns the same error.
- Only resend a credit top-up if the first request carried an
idempotencyKey. Without one, a retry is a new purchase. See Top-ups.
Are you charged for errors?
Almost never. A request rejected before it runs (400, 401, 402, 403, 413,
429) costs nothing, and a paid call that fails on our side (500, 503) is
refunded. Several entity lookups bill even when they find nothing — for
example a hotel property, financial instrument, or blue-collar company lookup
that returns 404 — because the lookup itself ran. The chargeInfo on a
response is always what you were charged. See Billing & credits.
Finding a failed call
API request history lists your organization's recent calls with status code, error code, path, and duration, so you can find a failed call from the error code a user reported.
| Operation | What it does | Reference |
|---|---|---|
| API request history | List recent API calls, filtered by status, error code, path, or time | listApiRequests |
Related
- Rate limits — how limits work and how to see yours.
- API keys — key ceilings, expiration, and revocation.
- Sync vs async — timeouts and polling.