Errors

Response shape

Every error — REST or failed stream event — uses one public code. REST errors return:

{
  "error": {
    "code": "invalid_request",
    "message": "human-readable summary",
    "status": 422
  }
}

A failed SSE frame carries the same code (no status).

Codes

Code	HTTP	Cause	What to do
`invalid_request`	422	You	Bad body — wrong shape, missing `query`, bad `geography`, non-HTTPS `webhook_url`.
`auth_required`	401	You	Send valid `X-Orakle-API-Key`.
`job_not_found`	404	You	Wrong or unowned job id.
`rate_limited`	429	You	Honor `Retry-After`.
`insufficient_data`	422	External	Not enough market data. Retry or refine.
`service_unavailable`	503	Us	Dispatch failure. Retry with backoff.
`internal_error`	500	Us	Retry; contact support if persistent.

You — fix request. Us — transient. External — upstream limit.

Rate limiting

Capped per minute and per hour, by API key. Health and webhook endpoints exempt. Exceeding returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Max N requests per minute.", "status": 429 } }

Wait at least Retry-After seconds before retrying. SDKs back off automatically.

Errors

Response shape

Codes

Rate limiting

On this page