Error Handling

Error Handling

General format

• Success responses include error: false and data.
• Error responses often include error: true and messages or message.

Common errors

• 401 Unauthorized — invalid/expired token
• 400 Bad Request — missing or invalid params
• 404 Not Found — invalid resource id
• 429 Rate Limit — slow down requests, implement exponential backoff
• 500 Internal Server Error — retry with backoff, optionally alert

Retries & backoff

• Use exponential backoff with jitter for retries.
• For non-idempotent requests (POST create), check response before retrying to avoid duplicates — prefer idempotency via external identifiers (e.g., external_account_identifier).

Logging

• Log full request and response (sanitized of secrets) for troubleshooting.
• Capture request IDs returned by the API for support escalations.