Skip to main content

Fault Tolerance

Errors can occur in any API integration. A reliable integration requires solid error handling and retry strategies.

Log errors​

If an endpoint returns an error, log the request as detailed as possible:

  • Request body (sent data)
  • Request headers
  • Response status code
  • Response body (error message)
  • Timestamp
  • API key (partial only, never full)

This helps with later diagnosis and allows you to retry requests when needed.

Retry strategy​

Some errors are temporary and can be resolved by retrying. Use this strategy:

Not retryable (errors that will not be fixed by retrying):

  • 401 — Authentication failed
  • 1002 — Validation failed
  • 1024 — Resource already exists

Retryable (temporary errors):

  • 429 — Rate limit exceeded
  • 500 — Server error
  • Network timeouts

Exponential backoff​

Use exponential backoff for retries:

  1. Attempt: immediately
  2. Attempt: wait 1 second
  3. Attempt: wait 2 seconds
  4. Attempt: wait 4 seconds
  5. Attempt: wait 8 seconds

Stop after a maximum of 5 attempts and report the error.

Rate limiting​

Current limits: 600 requests per minute per API key. Additionally, a maximum of 10 concurrent requests per API key is allowed.

If you receive 429:

  • Reduce request rate
  • Reduce the number of parallel requests (e.g., worker/queue limit)
  • Implement retries with backoff
  • Use a lower limit parameter where applicable
  • Spread requests over time

For header details (X-RateLimit-Limit, X-RateLimit-Remaining, X-ConcurrencyLimit-Limit, X-ConcurrencyLimit-Remaining) and error formats, see Rate Limiting.

Idempotency​

When possible, use unique IDs for idempotency:

# Safe to retry using a unique idempotency key
curl -X POST "https://YOUR_SERVER-api.mail2many.de/api/v1/subscribers" \
  -H "Idempotency-Key: unique-id-123" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

This allows safe retries without creating duplicates.

Monitoring​

Track these metrics:

  • Error rate per endpoint
  • Average response time
  • 5xx vs. 4xx errors
  • Authentication failures

This helps detect issues early.

Additional resources​

See also the Errors documentation for details about specific error codes.