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

# Error Handling

> How the Truedy API reports errors and how to handle them

# Error Handling

All API errors use a consistent JSON structure and appropriate HTTP status codes.

## Response format

Errors include a top-level `error` object and a `meta` object:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": {
      "field": "phone_number",
      "reason": "Must be in E.164 format"
    }
  },
  "meta": {
    "request_id": "uuid",
    "ts": "2026-02-04T12:00:00Z"
  }
}
```

* **code**: Machine-readable error code (e.g. `validation_error`, `not_found`, `rate_limit_exceeded`).
* **message**: Human-readable description.
* **details**: Optional object with extra context (validation fields, IDs, etc.).
* **meta.request\_id**: Use this when contacting support.
* **meta.ts**: Server timestamp of the response.

## HTTP status codes

| Status | Meaning                                                                                             |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400`  | Bad request (malformed body or query)                                                               |
| `401`  | Unauthorized (missing or invalid API key / JWT)                                                     |
| `402`  | Payment required (trial not started, trial expired, subscription inactive, or insufficient credits) |
| `403`  | Forbidden (e.g. IP not whitelisted)                                                                 |
| `404`  | Not found (resource or ID does not exist)                                                           |
| `422`  | Validation error (schema or business rule)                                                          |
| `429`  | Rate limit exceeded                                                                                 |
| `500`  | Internal server error                                                                               |
| `502`  | Bad gateway (external provider error, e.g. voice or telephony provider)                             |

## Common codes

* **validation\_error** (422): Check `details` for field-level errors. Business rules (e.g. no outbound number assigned) also return 422.
* **payment\_required** (402): Billing or usage limit. The API returns 402 when the organization has no active trial or paid plan, the trial has ended, the subscription is inactive, or there are insufficient credits for the operation (e.g. voice clone, widget, knowledge base). Use `error.details` for context:
  * **reason**: One of `trial_not_started`, `trial_expired`, `subscription_inactive`, or `insufficient_credits`.
  * **redirect\_url**: Optional URL to send the user (e.g. `/onboarding/trial` to start a trial, `/settings/billing` to update payment).
  * **balance** / **required**: For `insufficient_credits`, optional numeric fields indicating current balance and required amount.
  * Handle 402 by prompting the user to start a trial, subscribe, or upgrade, or by redirecting to the provided URL.
* **not\_found** (404): The resource or ID in the path/body does not exist.
* **unauthorized** (401): Provide a valid API key in the `Authorization: Bearer <key>` header.
* **forbidden** (403): Key is valid but action or origin is not allowed.
* **provider\_error** (502): An external provider (e.g. voice or telephony) failed. Check the error message or, for calls, `context.last_error` on the call record.
* **rate\_limit\_exceeded** (429): Respect `Retry-After` and rate limit headers.

## Best practices

1. Use `meta.request_id` in support requests and logs.
2. On `429`, back off using `Retry-After` and avoid tight retry loops.
3. Do not rely on message text for logic; use `error.code` and status codes.

For endpoint details and request bodies, see the [API Reference](/api-reference/introduction).