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

# Errors

> HTTP status codes and error formats returned by the Asisso API

## Error format

All errors return a JSON body with a `detail` field:

```json theme={null}
{
  "detail": "Human-readable error message"
}
```

For request validation failures (status `422`), `detail` is an array of field-level errors:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

***

## HTTP status codes

| Status | Meaning               | Common causes                                                            |
| ------ | --------------------- | ------------------------------------------------------------------------ |
| `400`  | Bad Request           | Missing required fields, invalid parameter values, unsupported operation |
| `401`  | Unauthorized          | Missing auth header, invalid or expired API key or JWT token             |
| `403`  | Forbidden             | Valid credentials but the resource belongs to a different organization   |
| `404`  | Not Found             | Resource ID does not exist or is not accessible to your organization     |
| `409`  | Conflict              | Duplicate resource (e.g., email already registered)                      |
| `422`  | Unprocessable Entity  | Request body or query parameter failed schema validation                 |
| `500`  | Internal Server Error | Unexpected server-side failure                                           |
| `501`  | Not Implemented       | Feature not supported in the current deployment                          |

***

## Workflow validation errors

When validating a workflow (or creating one with invalid nodes), the API returns structured errors that reference specific nodes, edges, or fields:

```json theme={null}
{
  "errors": [
    {
      "kind": "node",
      "id": "agent-1",
      "field": "data.prompt",
      "message": "Prompt cannot be empty"
    },
    {
      "kind": "edge",
      "id": "edge-3",
      "field": null,
      "message": "Edge target node does not exist"
    },
    {
      "kind": "workflow",
      "id": null,
      "field": null,
      "message": "Workflow must have exactly one Start Call node"
    }
  ]
}
```

| Field     | Type                             | Description                                                  |
| --------- | -------------------------------- | ------------------------------------------------------------ |
| `kind`    | `"node" \| "edge" \| "workflow"` | What the error applies to                                    |
| `id`      | string or null                   | Node or edge ID from the workflow definition                 |
| `field`   | string or null                   | Dot-notation path to the specific field (e.g. `data.prompt`) |
| `message` | string                           | Human-readable description of the problem                    |

***

## Telephony errors

Telephony operations may fail with one of these named error types returned in the `detail` field:

| Error                         | Description                                                      |
| ----------------------------- | ---------------------------------------------------------------- |
| `PROVIDER_MISMATCH`           | The request was routed to the wrong telephony provider           |
| `WORKFLOW_NOT_FOUND`          | The workflow ID in the inbound URL does not exist                |
| `ACCOUNT_VALIDATION_FAILED`   | Your telephony provider credentials are invalid                  |
| `PHONE_NUMBER_NOT_CONFIGURED` | The phone number is not set up in your telephony account         |
| `SIGNATURE_VALIDATION_FAILED` | Webhook signature verification failed (possible spoofed request) |
| `QUOTA_EXCEEDED`              | Your organization has exceeded its usage quota                   |
| `GENERAL_AUTH_FAILED`         | Generic authentication failure with the telephony provider       |

***

## Tips for handling errors

* **Retry on `500`** with exponential backoff — transient server errors can resolve on retry.
* **Do not retry `4xx`** — these indicate problems with your request that will not self-resolve.
* **Check `detail` carefully on `422`** — the `loc` array pinpoints exactly which field failed validation.
* **Store API keys securely** — a `401` on a previously working key likely means the key was archived.