Errors
Every Decryptr API error code, its HTTP status and what to do about it. Errors use the RFC 9457 problem details format.
Errors come back with a 4xx or 5xx status and a JSON body in the RFC 9457 problem details format, with content type application/problem+json:
{
"type": "https://www.decryptr.ai/developers/errors#rate_limited",
"title": "Rate limit reached",
"status": 429,
"code": "rate_limited",
"detail": "This request needs 25 calls; wait 4 s. Ask for a smaller limit to fit the remaining budget.",
"request_id": "3f6c2a8e-6a1f-4c1e-9d2b-0a5e7c1d9b42",
"limit": "burst",
"calls_requested": 25,
"retry_after": 4
}Branch on code: it is stable. title and detail are for people and can change. Quote request_id (the same as the X-Request-Id header) when you contact support. A refused request does no work and costs no calls. A lookup that finds nothing (404) is still charged what it asked for.
Some errors carry extra fields:
| Field | On | Meaning |
|---|---|---|
errors | invalid_parameter | One entry per bad parameter. |
required_scope | insufficient_scope | The scope the endpoint needs. |
required_plan | plan_upgrade_required | The lowest plan with this endpoint. |
max_items | limit_too_large | The most items or ids per request on your plan. |
history_days | history_limit | How many days back your plan reads. |
limit, calls_requested, retry_after | rate_limited, quota_exceeded | Which limit was reached (burst, minute or quota), the calls the request asked to reserve, and seconds to wait. |
max_streams | stream_limit | The open streams your plan allows. |
400 Bad request
| Code | Meaning |
|---|---|
invalid_parameter | A parameter has the wrong type or is out of range. errors names each one. |
unknown_parameter | A query parameter the endpoint does not take. We refuse these so a typo never returns unfiltered data. |
limit_too_large | limit, or the number of ids, is above what your plan allows in one request. max_items says how many. |
history_limit | The time range starts before your plan's history window. history_days says how far back you can read. |
key_in_query | A key was sent in the query string. Send it in a header, and rotate that key: it may be in logs. |
401 Unauthorised
| Code | Meaning |
|---|---|
missing_key | No key was sent. |
invalid_key | The key is malformed or not recognised. |
key_revoked | The key was revoked. |
key_expired | The key passed its expiry date. |
402 Payment required
| Code | Meaning |
|---|---|
payment_required | The subscription behind the key is unpaid after the 7 day grace period, or has been suspended. Sort out billing from your account. |
subscription_cancelled | The subscription was cancelled. |
403 Forbidden
| Code | Meaning |
|---|---|
insufficient_scope | The key does not have the scope for this endpoint. required_scope says which. |
plan_upgrade_required | Your plan does not include this endpoint. required_plan says which plan does. |
dataset_unavailable | The data behind this endpoint is switched off for now. |
key_suspended | We paused this key, for example after unusual use. Email [email protected] with the request_id. |
account_suspended | The account is suspended. Email [email protected]. |
404 Not found
| Code | Meaning |
|---|---|
not_found | No item with that id or symbol, or the path does not exist. |
405 Method not allowed
| Code | Meaning |
|---|---|
method_not_allowed | v1 is read only: use GET. |
429 Too many requests
Always sent with Retry-After. See Rate limits and quotas.
| Code | Meaning |
|---|---|
rate_limited | A per-second or per-minute limit was reached, or the request is larger than the burst bucket holds right now. |
quota_exceeded | Not enough calls left this month for this request. |
stream_limit | You already have your plan's number of open streams. Streams are the news signal stream (Pro and above) and the post stream (Business). Both count towards the same limit. |
too_many_auth_failures | Too many failed key checks from your client. Wait, then use a valid key. |
5xx Server errors
| Status | Code | Meaning |
|---|---|---|
| 500 | internal_error | Something failed on our side. Safe to retry with backoff. |
| 503 | api_disabled | The API is switched off for now. Retry after Retry-After. |
| 503 | overloaded | The API is busy. Retry with backoff. |
| 503 | query_timeout | The query took too long. Narrow the range or lower limit. |
Server errors cost no calls.
Rate limits and quotas
How the Decryptr API counts calls (one per item, weighted by endpoint), the limits per plan, the headers on every response, 429 and Retry-After, and a backoff example.
Pagination
How Decryptr API lists page with cursors, the response envelope, page sizes per plan and how pages are charged.