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
| status | meaning | charged | retry? |
|---|---|---|---|
200 | Success | Yes, the endpoint's price | n/a |
400 | A parameter is missing or invalid | No (yes if the call ran and the site rejected the value) | No: fix the request |
401 | Key missing, invalid, revoked or expired | No | No: fix the key |
402 | Out of credits, or a limit you set was reached | No | After a top-up or the reset |
403 | This key may not make this call | No | No: change the key's settings |
404 | No such endpoint, or the item doesn't exist or isn't public | Yes when the lookup ran (no such user, removed item); no for an unknown endpoint | No |
405 | Not a GET. Every endpoint is a GET. | No | No |
410 | A stored result is past its retention, or a listing was removed | No for stored results; yes for a removed listing | No: call the endpoint again |
429 | Your team's rate or concurrency limit | No | Yes, after retry-after |
502 | The source site failed this time | No | Yes, with backoff |
503 | Endpoint paused, or briefly unavailable | No | Yes, later |
504 | The call took far longer than usual | No | Yes, 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 with | what to do |
|---|---|
missing api key | Send your key in the x-api-key header (or Authorization: Bearer <key>). |
invalid api key | The key doesn't exist. Check for a truncated copy, or create a new one. |
this api key was revoked | Someone revoked it, or the account is suspended. Use another key. |
this API key has expired | Its expiry date has passed. Create a new key. |
402: payment required
| case | extra fields | what to do |
|---|---|---|
| Not enough credits for this call | credits_required, credits_remaining | Top up or start a plan. Auto top-up keeps this from happening. |
| Team spend limit reached | spend_limit (daily or monthly), limit, spent, resets_at | Wait for resets_at (UTC), or raise the limit in Billing. |
| This key's monthly credit cap reached | key_cap, key_spent, resets_at | Wait for resets_at (the 1st of next month, UTC), or raise the cap. |
403: forbidden
| message starts with | what 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 network | Your team only allows calls from listed IP addresses. Call from an allowed network, or ask a team admin to add yours. |
account suspended | Contact 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 includeretry-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,503and504. Don't retry other 4xx without changing something. - Honor
retry-afterwhen 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,503and504for you, honoringretry-after.
Messages in the dashboard
The dashboard and its sign-in can show these team rules. None affect API keys unless noted.
| code | means |
|---|---|
forbidden_role | Your role can't do that. Ask an owner or admin. |
mfa_required | The team requires two-factor login. Enroll to open it. |
member_limit | The team is at its member limit. |
sso_required | Your company signs in with single sign-on. |
ip_not_allowed | The team's dashboard is limited to listed networks. |
reauth_required | The team's session length has passed. Sign in again. |