Reference

Error Codes

Public API errors use one JSON envelope with a stable code, human-readable message, request ID, and optional details object.

Error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be valid JSON.",
    "request_id": "req_...",
    "details": {}
  }
}

Code	Status	What to do
authentication_required	401	Send `Authorization: Bearer <API_KEY>`.
permission_denied	403	Use a key with the required scope and workspace authorization.
organization_context_mismatch	403	Correct or remove `X-Organization-Id`.
workspace_id_required	400	Provide `X-Workspace-Id` when the key can access multiple workspaces.
missing_idempotency_key	400	Add `Idempotency-Key` to send-creating requests.
invalid_request	400	Fix invalid fields, malformed JSON, or unsupported values.
rate_limited	429	Wait for `Retry-After` or `X-RateLimit-Reset`.
quota_exceeded	409/429	Reduce volume or resolve usage/billing limits.
webhook_endpoint_not_found	404	Check the endpoint ID and workspace context.
webhook_event_not_found	404	Check the delivery/event ID and workspace context.
downstream_error	502	Retry later with backoff if the request is safe to retry.

Include the request_id from the error payload when contacting support. Do not include API keys or webhook secrets.