Errors

Every error has the same shape: an error object with a machine readable code and a human readable message, plus a request_id you can quote if you contact support. Most errors are about the input, and the message says exactly what to change.

Error response

{
  "error": {
    "code": "invalid_input",
    "message": "Unsupported country \"ZZ\". Use an ISO 3166-1 alpha-2 code such as US, ES or MX.",
    "details": { }
  },
  "request_id": "8b328ea4-9a86-4871-ab66-f4494dfb2fea"
}

details is present only when there is structured information to add, for example the credits required on a 402.

Status codes

Name
2xx
Description
The call succeeded and was charged. data and meta are present.
Name
4xx
Description
Something about the request needs to change: the key, the input, the balance or the pace. Nothing was charged, or the charge was refunded.
Name
5xx
Description
The data could not be produced. The charge was refunded. Retry once after a few seconds; if it persists, quote the request_id.

Error codes

Name
unauthorized
Type
401
Description
No key, an unknown key, or a revoked key. Create one under Settings » Developers and send it as Authorization: Bearer pk_live_....
Name
plan_required
Type
403
Description
The key is valid but the account's plan does not include the API. details.min_plan says which one does. Upgrade in Settings » Billing.
Name
invalid_input
Type
400
Description
A required field is missing or a value is out of range. The message names the field. Check Countries and languages for the accepted codes.
Name
insufficient_credits
Type
402
Description
The call costs more than your balance. details.required_credits and details.remaining_credits tell you by how much.
Name
daily_cap_reached
Type
429
Description
This key has hit its daily credit cap. details carries daily_cap, used_today and resets_at (00:00 UTC). Raise the cap in Settings » Developers or wait. Nothing was charged.
Name
not_found
Type
404
Description
Either the endpoint does not exist, or there is no data for that input: a domain with no rankings in that country, a private Instagram account, a hashtag with no recent posts. Refunded.
Name
rate_limited
Type
429
Description
More than 60 requests in a minute from one key. Wait the number of seconds in the Retry-After header.
Name
upstream_error
Type
502
Description
The data source did not return a usable result. Refunded. Safe to retry.
Name
timeout
Type
504
Description
The data source took too long. Social endpoints can take up to two minutes for large requests; ask for fewer posts. Refunded.
Name
not_configured
Type
503
Description
That data source is temporarily unavailable on our side. Refunded.

402 insufficient_credits

{
  "error": {
    "code": "insufficient_credits",
    "message": "This call costs 9 credits and your balance is 4.5.",
    "details": {
      "required_credits": 9,
      "remaining_credits": 4.5
    }
  },
  "request_id": "ace2a696-f014-43fb-adf9-a63e87229723"
}

404 not_found

{
  "error": {
    "code": "not_found",
    "message": "No organic data for example.com in ES. Check the spelling or try another country."
  },
  "request_id": "910da3b3-1954-46a5-a613-34a5263bb7b2"
}

Retrying

Retry 502, 503 and 504 once or twice with a short pause; they are refunded, so a retry costs the same as a first attempt. Do not retry 400, 401, 402 or 404: the result will be the same until you change the request, the key or the balance. On 429, honour Retry-After.

Inside an MCP client

Through the MCP server the same errors come back as tool results with isError: true and the text code: message, rather than as protocol errors. That is deliberate: the model sees "insufficient_credits: This call costs 9 credits and your balance is 4.5" and can tell you, instead of the client dropping the connection.