​

Errors and limits

​

Common HTTP statuses

• 200 successful read
• 201 successful creation
• 400 invalid request
• 401 unauthenticated
• 403 authenticated but not authorized
• 404 resource not found
• 429 rate limited
• 501 feature exists in the contract but is not enabled in the current deployment
• 5xx unexpected service error

​

Common error codes

• unauthorized
• forbidden
• invalid_token
• token_expired
• token_revoked
• scope_missing
• validation_failed
• rate_limited
• concurrency_limited
• quota_exceeded
• idempotency_conflict
• run_not_found
• not_implemented
• internal_error

​

Example error response

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "retryAfter": 60
  },
  "requestId": "req_123",
  "version": "v1"
}

​

Client guidance

• preserve requestId for support and debugging
• respect Retry-After on rate-limited responses
• treat not_implemented as a deliberate rollout gate, not a transient server failure
• do not collapse 401, 403, and 501 into the same retry path