Errors

Docs API uses conventional HTTP status codes to indicate the outcome of a request. Codes in the 2xx range mean success, 4xx codes signal a problem with the request, and 5xx codes indicate a rare error on our side.

The error object #

Every failed request returns a JSON body with an error object. The type field groups errors into broad categories, while code identifies the specific problem.

400 · JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: name.",
    "param": "name",
    "request_id": "req_Hd92kLpQ7m"
  }
}

HTTP status codes #

Status	Meaning
200	OK — the request succeeded.
201	Created — a new object was created.
400	Bad Request — the request was malformed or missing a parameter.
401	Unauthorized — no valid API key was provided.
403	Forbidden — the key lacks permission for this resource.
404	Not Found — the requested resource does not exist.
409	Conflict — the request conflicts with the current state.
429	Too Many Requests — you have hit the rate limit.
500	Server Error — something went wrong on our end.

Error codes #

Code	Type	Description
`parameter_missing`	invalid_request_error	A required parameter was not supplied.
`parameter_invalid`	invalid_request_error	A parameter had the wrong type or value.
`resource_missing`	invalid_request_error	No object exists with the given ID.
`authentication_failed`	authentication_error	The API key is missing, malformed, or revoked.
`permission_denied`	permission_error	The key is valid but lacks the required scope.
`idempotency_conflict`	idempotency_error	An idempotency key was reused with a different body.
`rate_limit_exceeded`	rate_limit_error	Too many requests in a short window.
`api_error`	api_error	An unexpected error occurred on our side.

Handling errors #

Inspect the status code first, then branch on error.code for specific handling. The official libraries raise typed exceptions you can catch directly.

try {
  await client.resources.create({ name: "" });
} catch (err) {
  if (err.code === "parameter_missing") {
    console.error(`Missing: ${err.param}`);
  }
}

from Docs API import InvalidRequestError

try:
    client.resources.create(name="")
except InvalidRequestError as err:
    if err.code == "parameter_missing":
        print(f"Missing: {err.param}")

Rate limits & retries #

The API allows up to 100 requests per second per key. When you exceed it, you receive a 429 with a Retry-After header. Retry 429 and 5xx responses with exponential backoff, and attach an Idempotency-Key to writes so retries never duplicate work.

Never retry a 4xx error other than 429 without changing the request — the result will be the same. Log the request_id from the error body so support can trace any issue quickly.