Reliability

Errors

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

Errors return stable codes and request IDs. Unsupported capability 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": "Connected account 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.
  • `provider_capability_not_supported`: the connected account cannot perform the requested action.
  • `rate_limited`: the per-key budget is exhausted. Read `Retry-After` (seconds) and the `x-ratelimit-remaining` header, then retry with backoff.