🛠️ 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 error object from failed responses — in particular name, detail, instance and problems. 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 Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests (respect Retry-After header if present)

Avoid retrying errors such as:

• 401 Unauthorized — likely invalid credentials
• 403 Forbidden — access denied
• 422 Unprocessable Entity — validation failed

🖥️ 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 instance and problems fields, which identify the endpoint and the specific fields that failed validation
• Timestamp, endpoint path and the idempotencyKey you 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.