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

# Errors

> Standard error format and error codes returned by the DialNexa API.

## Error format

When a request fails, the API returns an error object with three fields:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed: phone_number must be in E.164 format",
  "error": "Bad Request"
}
```

| Field        | Type            | Description                                                                                                          |
| ------------ | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `statusCode` | integer         | The HTTP status code.                                                                                                |
| `message`    | string or array | A human-readable description of the error. Validation errors may return an array of messages, one per invalid field. |
| `error`      | string          | The short HTTP status name (e.g., `"Bad Request"`, `"Not Found"`).                                                   |

### Validation error example

When multiple fields fail validation, `message` is an array:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "phone_number must be in E.164 format",
    "agent_id should not be empty"
  ],
  "error": "Bad Request"
}
```

## HTTP status codes

| Code  | Name                  | When it occurs                                                                                                                    |
| ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `200` | OK                    | The request succeeded. Returned for GET, PATCH, and DELETE operations.                                                            |
| `201` | Created               | A new resource was created successfully. Returned for POST operations.                                                            |
| `400` | Bad Request           | The request body or query parameters failed validation.                                                                           |
| `401` | Unauthorized          | Missing or invalid API key.                                                                                                       |
| `403` | Forbidden             | Your API key does not have permission, or the requested destination is blocked by workspace Telephony Config.                     |
| `404` | Not Found             | The requested resource does not exist, or does not belong to your organization.                                                   |
| `409` | Conflict              | The operation conflicts with the current state, for example registering a phone number that already exists.                       |
| `422` | Unprocessable Entity  | Some platform services may use this for semantic validation. Only depend on it when the endpoint contract lists a `422` response. |
| `429` | Too Many Requests     | A gateway or service rate limit was reached. Retry with backoff; honor `Retry-After` only when that header is present.            |
| `500` | Internal Server Error | An unexpected error occurred on our side. If this persists, contact support.                                                      |

## Handling errors in code

### TypeScript / JavaScript

```typescript theme={null}
async function createCall(apiKey: string, agentId: string, phoneNumber: string) {
  const response = await fetch("https://api.dialnexa.com/v1/calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: agentId,
      phone_number: phoneNumber,
      metadata: {},
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(
      `API error ${error.statusCode}: ${
        Array.isArray(error.message) ? error.message.join(", ") : error.message
      }`
    );
  }

  return response.json();
}
```

### Python

```python theme={null}
import requests

def create_call(api_key: str, agent_id: str, phone_number: str) -> dict:
    response = requests.post(
        "https://api.dialnexa.com/v1/calls",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={
            "agent_id": agent_id,
            "phone_number": phone_number,
            "metadata": {},
        },
    )

    if not response.ok:
        error = response.json()
        msg = error.get("message", "Unknown error")
        if isinstance(msg, list):
            msg = ", ".join(msg)
        raise Exception(f"API error {error.get('statusCode')}: {msg}")

    return response.json()
```

## Common mistakes

**`401 Unauthorized`** - Your API key is missing, malformed, or has been revoked. Check that you are passing `Authorization: Bearer YOUR_API_KEY` and that the key has not expired.

**`400 Bad Request` on phone numbers** - Phone numbers must be in E.164 format: `+` followed by the country code and number, with no spaces or dashes. For example, `+919876543210` not `9876543210`.

**`403 Forbidden` on outbound destinations** - The destination number is valid, but the route is not enabled for your workspace. Check **Workspace Settings > Telephony Config** for the destination country and network-group prefix, or use an enabled SIP/BYOC route.

**`404 Not Found`** - The resource ID is correct but the resource belongs to a different organization. All resources are scoped to the organization associated with your API key.

**`409 Conflict`** - You are trying to perform an action that is not valid for the current state of the resource. For example, registering a phone number that already exists or applying a status action that the resource cannot accept.

## Retry decision table

| Situation                                | Retry? | Recommended action                                                                                                                                     |
| ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Network timeout before any response      | Maybe  | Check whether the operation has side effects before retrying. For create or call operations, first look for the resource by your own correlation data. |
| `400`, `401`, `403`, `404`, or `409`     | No     | Fix the request, credentials, permissions, resource ID, or resource state.                                                                             |
| `429`                                    | Yes    | Use exponential backoff with jitter. Honor `Retry-After` when the response includes it.                                                                |
| `500`, `502`, `503`, or `504` on a read  | Yes    | Retry with capped exponential backoff.                                                                                                                 |
| `500`, `502`, `503`, or `504` on a write | Maybe  | Retry only when the endpoint page marks the action retry safe or you can confirm the first attempt did not take effect.                                |

See [Reliability and retries](/docs/api-reference/reliability) for production-safe retry patterns and current platform guarantees.