Errors

Errors use standard HTTP status codes and a consistent JSON body.

{
  "error": {
    "code": "validation_failed",
    "message": "title must be at most 200 characters",
    "request_id": "req_01J9Z8K2M4",
    "details": {
      "field": "title"
    }
  }
}

Status	Code	Meaning
400	`invalid_request`	The request is malformed or a parameter has the wrong type.
401	`unauthorized`	The token is missing, expired or revoked.
402	`quota_exceeded`	A plan limit was reached.
403	`forbidden`	The token lacks the required scope or the role is insufficient.
404	`not_found`	The object does not exist or is not visible to you.
409	`conflict`	The object changed since you read it (If-Match mismatch).
410	`gone`	The object was permanently deleted.
413	`payload_too_large`	The body exceeds the limit for this endpoint.
422	`validation_failed`	One or more fields failed validation; see error.details.
429	`rate_limited`	Too many requests; retry after the time in Retry-After.
500	`internal_error`	Something went wrong on our side.
503	`unavailable`	Temporarily unavailable; retry with backoff.

Always log request_id; support can find a request with it.