Errors, limits and idempotency

Consistent problems, a request id on every response, and safe retries.

403json

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Production environments are restricted to owners and admins.",
    "request_id": "req_…"
  }
}

code	Meaning
INVALID_REQUEST	a field is missing or malformed; the message says which
UNAUTHENTICATED	no or invalid key
FORBIDDEN	the key’s scopes or your role do not allow this
POLICY_DENIED	an organisation policy refused it
NOT_FOUND	no such task, device, key or webhook in your organisation
INVALID_STATE	the task is not in a state where this action applies
IDEMPOTENCY_MISMATCH	the same Idempotency-Key was used with a different body
RATE_LIMITED	slow down; Retry-After says how long

Idempotency

Send an Idempotency-Key header when creating a task. Repeating the same key with the same body returns the original task; the same key with a different body is refused.

Rate limits

Every actor is rate-limited with a token bucket. When you are limited you receive 429 with Retry-After. Streams are not counted against the bucket once open.

Was this page helpful?

PreviousCredits Next What is stored where