Errors

Error response format

All API errors return a JSON body:

{
  "error": "provider config not found",
  "code": "not_found"
}

Field	Description
`error`	Human-readable error message
`code`	Machine-readable error code

The X-Request-Id response header is included on every response for debugging and support.

HTTP status codes

Status	Meaning
`400`	Bad request — invalid parameters or missing required fields
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — API key doesn’t have permission (e.g., publishable key on a secret-only endpoint)
`404`	Not found — resource doesn’t exist in this workspace
`409`	Conflict — duplicate resource (e.g., provider config already exists for this provider)
`422`	Unprocessable — request is well-formed but semantically invalid
`429`	Rate limited — too many requests
`500`	Internal server error
`502`	Bad gateway
`503`	Service unavailable
`504`	Gateway timeout

Common error codes

Code	Description
`not_found`	Resource not found
`already_exists`	Resource already exists (duplicate)
`invalid_request`	Missing or invalid parameters
`unauthorized`	Authentication failed
`forbidden`	Insufficient permissions
`rate_limited`	Too many requests
`provider_error`	Upstream provider returned an error
`refresh_failed`	Token refresh failed
`needs_reauth`	Connection requires re-authorization

Retry guidance

The SDKs automatically retry on these status codes with exponential backoff:

Status	Retry?	Notes
`429`	Yes	Respect `Retry-After` header if present
`500`	Yes	Server error, may be transient
`502`	Yes	Bad gateway
`503`	Yes	Service temporarily unavailable
`504`	Yes	Gateway timeout
`400-404`	No	Client error, fix the request

Retry strategy: up to 3 attempts with exponential backoff (500ms, 1s, 2s base delay, capped at 4s). The Go SDK adds random jitter.

SDK error handling

// Node
import { AuthpipeApiError } from "@authpipe/node";

try {
  await authpipe.getCredential({ provider: "slack", tenantId: "org_acme" });
} catch (err) {
  if (err instanceof AuthpipeApiError) {
    err.statusCode  // 404
    err.code        // "not_found"
    err.message     // "connection not found"
    err.requestId   // "req_abc123"
  }
}

// Go
var apiErr *authpipe.APIError
if errors.As(err, &apiErr) {
  apiErr.StatusCode // 404
  apiErr.Code       // "not_found"
  apiErr.Message    // "connection not found"
  apiErr.RequestID  // "req_abc123"
}

# Python
from authpipe.errors import AuthpipeAPIError

try:
    client.get_credential(provider="slack", tenant_id="org_acme")
except AuthpipeAPIError as e:
    e.status_code  # 404
    e.code         # "not_found"
    e.message      # "connection not found"