Errors
RFC 9457 problem+json with stable machine-readable codes — the complete catalog.
All failures return application/problem+json (RFC 9457)
with a stable code your programs can branch on. Message texts may improve over time; codes
never change meaning.
{
"type": "https://endpointry.com/docs/errors#rate-limit-exceeded",
"title": "Rate limit exceeded",
"status": 429,
"code": "RATE_LIMIT_EXCEEDED",
"detail": "Too many requests. Slow down and honor the Retry-After header.",
"request_id": "req_926e84c25986fb884ae6fae2"
}Anatomy
| Field | Meaning |
|---|---|
type | Deep link to the code's documentation (an anchor in this page) |
title | Human-readable summary (stable per code) |
status | HTTP status, duplicated for convenience |
code | The field to branch on — stable, machine-readable |
detail | Human-readable specifics for this occurrence |
request_id | Correlation id — include it in support requests |
Complete code catalog
This table is generated from the platform's error definitions — it is always in sync with the
gateway. Each code below is an anchor target: a problem response's type links straight to it.
| Code | HTTP | Retry? | Meaning |
|---|---|---|---|
VALIDATION_ERROR | 400 | No | A parameter failed validation, or a cursor was malformed. Fix the request; do not retry as-is. |
UNAUTHORIZED | 401 | No | The API key is missing, malformed or revoked. Check the Authorization header. |
FORBIDDEN | 403 | No | The key is valid but not allowed to perform this operation. |
NOT_FOUND | 404 | No | The requested resource does not exist. Deterministic — retrying will not change the outcome. |
ENDPOINT_NOT_FOUND | 404 | No | No such endpoint. Check the path against the API reference. |
RATE_LIMIT_EXCEEDED | 429 | Yes | Requests per second exceeded. Honor Retry-After, then retry. |
QUOTA_EXCEEDED | 429 | No | The monthly quota is exhausted. Upgrade the plan or wait for the reset. |
TIMEOUT | 504 | Yes | The operation did not complete within the time budget. Safe to retry. |
TEMPORARILY_UNAVAILABLE | 502 | Yes | The service could not complete this request just now. Retry with backoff. |
SERVICE_UNAVAILABLE | 503 | No | The requested capability is not available on this deployment. |
INTERNAL_ERROR | 500 | No | Unexpected platform error. Contact support with the request_id if it persists. |
Code reference
VALIDATION_ERRORHTTP 400not retryableA parameter failed validation, or a cursor was malformed. Fix the request; do not retry as-is.
FORBIDDENHTTP 403not retryableThe key is valid but not allowed to perform this operation.
NOT_FOUNDHTTP 404not retryableThe requested resource does not exist. Deterministic — retrying will not change the outcome.
ENDPOINT_NOT_FOUNDHTTP 404not retryableNo such endpoint. Check the path against the API reference.
RATE_LIMIT_EXCEEDEDHTTP 429retryableRequests per second exceeded. Honor Retry-After, then retry.
QUOTA_EXCEEDEDHTTP 429not retryableThe monthly quota is exhausted. Upgrade the plan or wait for the reset.
TIMEOUTHTTP 504retryableThe operation did not complete within the time budget. Safe to retry.
INTERNAL_ERRORHTTP 500not retryableUnexpected platform error. Contact support with the request_id if it persists.
Retry guidance
- Retry only the codes marked retryable, with exponential backoff and jitter.
- On
429, honor theRetry-Afterheader instead of guessing. - Never retry
NOT_FOUNDorVALIDATION_ERROR— the result is deterministic. - Treat unknown codes as non-retryable and surface them; new codes may be added (that is not a breaking change — see Versioning).