Reliability

Errors

Handle validation, auth, conflict, capability, provider, and rate-limit errors consistently.

Errors return stable codes and request IDs. Provider-specific unsupported behavior should return `provider_capability_not_supported`.

Envelope

Every error returns an `error` object with a stable code and human-readable message.

Error responsejson
{
  "error": {
    "code": "provider_capability_not_supported",
    "message": "Provider has no tasks support.",
    "request_id": "req_123"
  }
}

Common codes

Clients should branch on the code, not on the message.

  • `bad_request`: invalid input or missing field.
  • `unauthorized`: missing or invalid API key.
  • `forbidden`: key lacks scope or session policy blocks the action.
  • `not_found`: resource is not in the current organization/application scope.
  • `conflict`: stale etag, revoked connection, or incomplete authorization.
  • `rate_limited`: retry after the documented limit window.