Errors

Stable error envelope

{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key.",
    "requestId": "req_123"
  }
}

Expect a stable JSON envelope and use the error code for logic, not the human message alone.

Common public error codes

• missing_api_key
• invalid_api_key
• credential_not_found
• credential_revoked
• credential_expired
• workspace_public_api_disabled
• workspace_public_api_suspended
• forbidden
• rate_limited
• insufficient_credits
• internal_error

Status code guidance

• 401: missing or invalid authentication
• 402: insufficient credits for the requested work
• 403: authenticated but not allowed
• 404: the requested resource was not found
• 429: rate limited; check Retry-After