Best Practices
Best practices for managing API errors and implementing resilient retry logic
Get Markdown🛠️ Best Practices for Handling API Errors
This section helps you build robust error handling into your integration by outlining retry strategies, logging recommendations, and resilience tips for production environments.
✅ General Error Handling Guidelines
- Check HTTP status codes on every response and avoid assuming success.
- Never retry client errors (
4xx) unless you've resolved the issue (e.g. fix validation or credentials). - Retry transient server errors (
5xx) and rate limiting errors (429) using exponential backoff. - Log the whole
errorobject from failed responses — in particularname,detail,instanceandproblems. Quoting these back to us is the fastest way for support to find your request. - Map errors to user-friendly messages so end users see clear, actionable feedback.
⏱️ Retry Strategies
Retrying failed requests is often necessary, but should be done thoughtfully:
- Use exponential backoff (e.g., 1s → 2s → 4s...) when retrying to reduce load
- Cap retries (e.g., maximum of 5 attempts) to avoid infinite loops
- Always retry:
500 Internal Server Error502 Bad Gateway503 Service Unavailable429 Too Many Requests(respectRetry-Afterheader if present)
Avoid retrying errors such as:
401 Unauthorized— likely invalid credentials403 Forbidden— access denied422 Unprocessable Entity— validation failed
Idempotency conflicts (409)
A 409 on a request with an idempotencyKey tells you what happened to the original request with that key:
IDEMPOTENCY_IN_FLIGHT— the original request is still running. Retry with the same key and payload after theRetry-Afterheader's number of seconds, and you'll get the original response.IDEMPOTENCY_ABANDONED— the original request was interrupted before its outcome was recorded, so it can't be replayed or safely retried. Check the resource's status (for example, list payments) before deciding to send a new request with a new key.
🖥️ Logging & Monitoring
Hands In logs all error responses on your behalf, including status codes, error names, request details, and timestamps. We actively monitor for spikes, failures, and rate limit breaches to help ensure platform stability.
You do not need to implement your own error logging to benefit from this monitoring — but you can choose to do so for internal debugging or observability.
If you do wish to implement custom error logging, we recommend capturing:
- HTTP status code, error name, and detail
- The
instanceandproblemsfields, which identify the endpoint and the specific fields that failed validation - Timestamp, endpoint path and the
idempotencyKeyyou sent - Alerts for any recurring errors (e.g.,
429,422,5xx)
For more information, refer to Error Formatting and Error Codes for error response structure and error code listings.