Errors and safe retries

Handle errors by category and preserve the customer’s work whenever a retry is safe.

Validation errors

Treat 400 responses as request corrections. Do not retry unchanged invalid payloads.

{
  "statusCode": 400,
  "message": "Missing x-tenant-id header.",
  "error": "Bad Request"
}

Authentication and permission errors

• 401: obtain a valid token before retrying.
• 403: the authenticated user lacks the required feature or permission. Retrying unchanged credentials will not help.

{
  "statusCode": 403,
  "message": "Insufficient product permission.",
  "error": "Forbidden"
}

Rate limits

Respect retryAfterSeconds when present and add jitter before retrying.

{
  "statusCode": 429,
  "message": "Too many verification-session create attempts. Please retry shortly.",
  "code": "VERIFICATION_CREATE_RATE_LIMITED",
  "retryAfterSeconds": 60
}

Idempotent creation

Send an Idempotency-Key for verification-session creation.

• Reuse it when retrying the exact same request after a timeout or uncertain response.
• Generate a new key for a new customer action.
• A reused key with a different payload returns 409 idempotency_key_conflict.

Server and network failures

Retry transient network errors and 5xx responses with bounded exponential backoff. Keep the same idempotency key when the original creation result is unknown. Stop after a small attempt limit and surface an operational error instead of retrying indefinitely.