Errors

Errors are readable and honest, and most are free. You pay for calls that run: a 200, or a lookup that ran but found nothing, like a 404 for a username that doesn't exist. Calls we refuse before running them (a missing or misspelled parameter, a key problem, no credits, your own limits) and every failure on our side (5xx, timeouts) cost 0 credits. Each response says what it cost in credits_used and the x-credits-used header. The body always says what went wrong in plain words, and often how to fix it.

HTTP/1.1 402 Payment Required
x-request-id: 3f1c9a…

{
  "success": false,
  "error": "insufficient credits: this call costs 3 credits and your balance is 1. Add credits at https://app.api.sh/billing",
  "credits_required": 3,
  "credits_remaining": 1
}

Every response carries an x-request-id. Quote it when you contact us and we can see exactly what happened.

At a glance

statusmeaningchargedretry?
200SuccessYes, the endpoint's pricen/a
400A parameter is missing or invalidNo (yes if the call ran and the site rejected the value)No: fix the request
401Key missing, invalid, revoked or expiredNoNo: fix the key
402Out of credits, or a limit you set was reachedNoAfter a top-up or the reset
403This key may not make this callNoNo: change the key's settings
404No such endpoint, or the item doesn't exist or isn't publicYes when the lookup ran (no such user, removed item); no for an unknown endpointNo
405Not a GET. Every endpoint is a GET.NoNo
410A stored result is past its retention, or a listing was removedNo for stored results; yes for a removed listingNo: call the endpoint again
429Your team's rate or concurrency limitNoYes, after retry-after
502The source site failed this timeNoYes, with backoff
503Endpoint paused, or briefly unavailableNoYes, later
504The call took far longer than usualNoYes, in about a minute

400: bad request

A required parameter is missing, or a value isn't valid (a malformed URL, an unknown option, a number out of range). The message names the parameter. Check the endpoint's docs page for accepted values. We check parameters before running the call, so these cost nothing. Rarely, a call runs and the site itself rejects a value (filters it doesn't accept, for example); that call ran, so it costs the endpoint's price, and credits_used says so.

401: unauthorized

message starts withwhat to do
missing api keySend your key in the x-api-key header (or Authorization: Bearer <key>).
invalid api keyThe key doesn't exist. Check for a truncated copy, or create a new one.
this api key was revokedSomeone revoked it, or the account is suspended. Use another key.
this API key has expiredIts expiry date has passed. Create a new key.

402: payment required

caseextra fieldswhat to do
Not enough credits for this callcredits_required, credits_remainingTop up or start a plan. Auto top-up keeps this from happening.
Team spend limit reachedspend_limit (daily or monthly), limit, spent, resets_atWait for resets_at (UTC), or raise the limit in Billing.
This key's monthly credit cap reachedkey_cap, key_spent, resets_atWait for resets_at (the 1st of next month, UTC), or raise the cap.

403: forbidden

message starts withwhat to do
this API key isn't allowed to call …The key is limited to certain endpoints; allowed_routes lists them. Edit the key or use another.
this API key can't be used from your networkYour team only allows calls from listed IP addresses. Call from an allowed network, or ask a team admin to add yours.
account suspendedContact us.

Key settings apply within about a minute, so a call right after a change can still see the old rule.

404: not found

Either the route doesn't exist (check the path against the catalog; free), or the endpoint ran and the item you asked for isn't there: a wrong id, a username that doesn't exist, a deleted listing, a private profile. That lookup ran, so it costs the endpoint's price, the same as a 200. We never return a 404 because a source site failed; that's a 502, and it's free.

404 and 410 on /v1/results

/v1/results/{id} answers 404 for an unknown id (or when your team keeps no responses) and 410 when the result is older than your retention, 30 days by default.

429: too many requests

Teams with a contract rate limit (requests per second) or concurrency limit (calls in flight) get 429 when they go over. The body says which (limit: rps or concurrency), and the retry-after header says how many seconds to wait. Accounts without such a limit don't see this status.

5xx: our side

Always free, whatever the call did before it failed.

  • 502: the source site failed or refused this time, usually for a moment. Retry with backoff.
  • 503: the endpoint is paused for maintenance, or a dependency is briefly down. May include retry-after. Check status.
  • 504: the call ran far past its usual time. Retry in a minute: the work often finishes in the background and the retry is answered from the cache, fast.

How to retry

  • Retry 429, 502, 503 and 504. Don't retry other 4xx without changing something.
  • Honor retry-after when it's there. Otherwise back off exponentially with jitter (about 1, 2, 4, 8 seconds) and stop after 4 or 5 tries.
  • Retries are safe: every endpoint is a read-only GET, and failed attempts (429, 5xx) cost nothing.
  • The SDKs retry 502, 503 and 504 for you, honoring retry-after.

Messages in the dashboard

The dashboard and its sign-in can show these team rules. None affect API keys unless noted.

codemeans
forbidden_roleYour role can't do that. Ask an owner or admin.
mfa_requiredThe team requires two-factor login. Enroll to open it.
member_limitThe team is at its member limit.
sso_requiredYour company signs in with single sign-on.
ip_not_allowedThe team's dashboard is limited to listed networks.
reauth_requiredThe team's session length has passed. Sign in again.