Error Handling and Retries

When to Retry

DO retry on these status codes:

• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

These indicate temporary server-side issues that typically resolve within seconds.

DO NOT retry on these status codes:

• 400 Bad Request - Fix the request format
• 401 Unauthorized - Check your authentication token
• 403 Forbidden - Verify organization permissions
• 422 Unprocessable Entity - Fix validation errors

Retry Strategy

Use exponential backoff with jitter:

• 1st retry: wait 1 second
• 2nd retry: wait 2 seconds
• 3rd retry: wait 4 seconds
• Maximum: 3-5 retry attempts

Idempotency

The POST /v1/requests endpoint is idempotent. Duplicate requests return:

• 200 OK with is_duplicate: true
• Same request_uuid as the original

This makes retries safe—you won't create duplicate privacy requests.