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.