Errors & API rate limits

Every non-2xx response from the API uses one envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request",
    "requestId": "9f0c1c2e-…",
    "docs": "https://limitry.com/docs/errors/#invalid_request",
    "details": [{ "path": "name", "message": "Required" }]
  }
}

• code is a small, stable set your integration may branch on.
• message is human-readable and may change — never parse it.
• requestId matches the X-Request-Id response header; include it when contacting support so a request can be found in the logs.
• details appears on validation failures, with one entry per field.
• docs links to the code’s entry below — how to fix it.

Error codes

Branch on code, never on message. Every error from a public code also carries docs, a link to its entry below. New codes may be added over time, so treat an unknown code like internal_error.

unauthorized

401 — the credential is missing, malformed, invalid, revoked, or expired. Fix: send Authorization: Bearer <key or token> with a live credential; create a new one if it was revoked or has expired.

forbidden

403 — the credential is valid but not allowed to do this: it was not granted the endpoint’s scope, your workspace role does not allow it, or a personal access token cannot act in the workspace named by X-Workspace. Fix: use a credential with the needed access (the message names the missing scope).

not_found

404 — the resource does not exist, or is not yours to see. Fix: check the path and the id; ids from another workspace are not found.

method_not_allowed

405 — the path exists, but not with this method. Fix: use one of the methods in the Allow response header.

invalid_request

400 — the request failed validation. Fix: read details, one entry per invalid field (path and message), and correct the request.

rate_limited

429 — the credential’s quota is exhausted (API rate limits). Fix: wait for the Retry-After seconds, then retry with backoff.

idempotency_key_reused

409 — this Idempotency-Key was already used for a different request. Fix: use a new key for a new operation; reuse a key only to retry the same request (Idempotency).

idempotency_in_progress

409 — a request with the same Idempotency-Key is still running. Fix: wait for the Retry-After seconds, then retry with the same key.

internal_error

500 — something failed on our side. Fix: retry with backoff; if it persists, contact support with the requestId.

API rate limits

Every authenticated request counts against a per-credential quota (per API key on the workspace endpoints; per token on /v1/user/*). Exhausting it returns:

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

with code: "rate_limited". Honor Retry-After and retry with backoff; limits are per credential, so one busy integration does not starve another key’s traffic.