> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airlead.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors, retries, and limits

> Handle Airlead integration failures without duplicating leads or overwhelming an endpoint.

# Errors, retries, and limits

## HTTP status handling

| Status        | Typical meaning                                                                 |
| ------------- | ------------------------------------------------------------------------------- |
| `200` / `201` | Request processed; inspect the response status for replay or duplicate outcomes |
| `400`         | Invalid JSON, missing required data, or failed validation                       |
| `401`         | Missing or invalid secret                                                       |
| `403`         | Credential or resource configuration does not permit the action                 |
| `404`         | Resource or transaction not found                                               |
| `409`         | Request is ambiguous or conflicts with current state                            |
| `429`         | Rate limit reached                                                              |
| `5xx`         | Temporary service or downstream failure may have occurred                       |

Error bodies are JSON and can include an `error`, `code`, validation details, or a structured acceptance result. Log the response body after removing personal data.

## Retry policy

Retry:

* network timeouts
* connection failures
* `429`
* temporary `5xx`

Do not retry unchanged:

* `400`
* `401`
* `403`
* most `404` responses

Use exponential backoff with jitter, for example 1, 2, 4, 8, and 16 seconds, and honor `Retry-After` when present.

## Make retries safe

### Ingest

Reuse the original `externalId`. A successful replay can return `status: "idempotent_replay"` with the existing lead ID.

### Buyer delivery

Deduplicate incoming events by `transactionId`. Return `2xx` for a transaction you already accepted.

### Lifecycle callbacks

Reuse the same transaction reference and desired state. A response can indicate that the transition was already applied; treat that as success.

## Rate limits

Limits vary by integration surface and may change to protect the service. Connect endpoint resolution is particularly guarded against repeated or guessed IDs.

Design clients to:

* cache successful configuration lookups when appropriate
* avoid polling invalid IDs
* limit concurrency
* honor `429` and `Retry-After`
* stop after a bounded number of attempts

## What to record

For each request, keep:

* timestamp
* environment
* endpoint family
* external ID or transaction ID
* HTTP status
* sanitized response code and message
* retry attempt number

Never log webhook secrets or full personal payloads.