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

# Errors and Error Codes

> Map HTTP status and error_code to retry, remediation, and escalation actions for production integrations.

# Production clients should classify failures into operator actions.

Callaro non-2xx responses include `error_code`. Use both `status` and `error_code` to decide whether to retry, reconfigure, or escalate.

## Operator response matrix

| Status | Example error\_code                              | Typical endpoint families                           | Operator action                                                    |
| ------ | ------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------ |
| 401    | `UNAUTHORIZED`, `JWT_REQUIRED`                   | Any authenticated endpoint                          | Validate token/key, environment, and auth model                    |
| 403    | `FORBIDDEN`                                      | Scoped key endpoints (campaigns, contacts, billing) | Grant missing scope or use correct key type                        |
| 404    | `SESSION_NOT_FOUND`, resource-specific not found | Voice sessions, contacts, campaign detail           | Verify ID and tenant context                                       |
| 422    | `VALIDATION_ERROR`, domain-specific codes        | Create/update/launch operations                     | Fix payload/business preconditions and retry                       |
| 429    | Rate limit codes                                 | High-volume list and mutation workloads             | Backoff and throttle worker concurrency                            |
| 5xx    | `INTERNAL_ERROR`                                 | Any                                                 | Retry with capped backoff; escalate with request\_id if persistent |

## Retry policy guidance

* Retry: network failures, 429, and selected transient 5xx errors.
* Do not retry blindly: 401, 403, most 404, and structural 422 errors.
* Record `request_id` for all failed requests.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.callaro.ai/api/v1/voice_sessions/999999" \
    -H "X-Api-Key: $CALLARO_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.callaro.ai/api/v1/voice_sessions/999999', {
    headers: { 'X-Api-Key': process.env.CALLARO_API_KEY }
  });
  const payload = await response.json();
  if (!response.ok) {
    const retryable = response.status === 429 || response.status >= 500;
    console.error({
      status: response.status,
      error_code: payload.error_code,
      message: payload.error,
      request_id: payload.request_id,
      retryable
    });
  }
  ```
</CodeGroup>

## Endpoint-family examples

* **Campaign launch**: 422 usually indicates missing contacts, schedule issues, or invalid campaign configuration.
* **Contacts import/export**: 422 often signals invalid CSV mapping or payload schema.
* **Phone number purchase**: 422 may indicate region/provider constraints.
* **Billing allocation**: 403/422 should be reviewed for partner scope and payload correctness.

<Warning>
  Never classify all 4xx responses as permanent and all 5xx responses as safe retries. Use endpoint context and error code semantics to avoid duplicate side effects.
</Warning>