Errors and rate limits

Handle Authlane error envelopes, retry headers, idempotency, and safe backoff.

Every API response uses the same data/error shape, and SDKs preserve it as a non-throwing result for expected failures.

Prerequisites

Keep the HTTP status, response headers, and stable error.code available at your server boundary.

Implement the workflow

{
  "data": null,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "hint": "Maximum 100 requests per 60 seconds",
    "docUrl": "https://authlane.io/docs/api-reference/errors-and-rate-limits",
    "statusCode": 429
  }
}

message and code are required. hint, docUrl, and statusCode may be absent. Common stable codes include UNAUTHORIZED, INSUFFICIENT_SCOPE, VALIDATION_ERROR, NOT_FOUND, OAuth and connection lifecycle codes, RATE_LIMIT_EXCEEDED, and INTERNAL_ERROR. SDK-local failures also include NETWORK_ERROR, TIMEOUT_ERROR, INVALID_RESPONSE, ADAPTER_ERROR, TOOL_NOT_AVAILABLE, and CREDENTIAL_LEASE_ERROR.

Every rate-limited API response reports X-RateLimit-Limit, X-RateLimit-Remaining, and the Unix timestamp X-RateLimit-Reset. A 429 also includes integer seconds in Retry-After.

Expected result

Clients branch on error.code, honor response headers, and expose a safe application message.

Handle errors

Retry safe reads after Retry-After with bounded exponential backoff and jitter. Retry 5xx, timeouts, or network failures only when the operation is safe or your application can prove idempotency. Authlane does not advertise an idempotency key for ordinary API mutations.

Lifecycle webhooks are the exception: Idempotency-Key is the stable event ID across delivery retries. Store it before side effects and return a fast 2xx for duplicates.

Security boundary

Do not log authorization headers, raw connect URLs, OAuth codes, credential leases, or provider bodies while diagnosing an error.

Next step

Open the Full OpenAPI reference navigation tab for exact operations and schemas.