Errors and retries

Errors use application/problem+json. Use the HTTP status for control flow, the stable problem type or title for classification, and the request ID when contacting support. The Gateway normalizes service-specific errors at the public boundary.

Example permission problem

{
  "type": "https://docs.connectplane.com/problems/forbidden",
  "title": "permission_denied",
  "status": 403,
  "detail": "The API key does not grant this operation.",
  "request_id": "01J..."
}

Retry 429 and transient 5xx responses with bounded exponential backoff and jitter, respecting Retry-After when present. Do not automatically retry validation, authentication, authorization, or version-conflict responses.

Common stable titles include invalid_request, authentication_required, permission_denied, not_found, conflict, rate_limited, unavailable, and timeout.

The Markdown version of this guide remains available for tools and compatibility consumers.