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

# Errors

> The error envelope, stable error codes, and the formats older endpoints still use.

Errors use conventional HTTP status codes: `4xx` means the request has to change,
`5xx` means retry later. Messages are always in English and may be reworded - do
not match on them.

## The error envelope

Most errors return this body:

```json theme={null}
{
  "error": "mf-core:tool-not-found",
  "message": "Tool not found",
  "details": {}
}
```

| Field | Meaning |
| - | - |
| `error` | Stable, machine-readable code in the form `mf-core:<name>`. **Branch on this field.** |
| `message` | Human-readable explanation for logs and support. |
| `details` | Optional context, for example the exhausted `policy` on a `429`. May be empty. |

Codes shared by every endpoint:

| Status | `error` | Meaning |
| - | - | - |
| `429` | `mf-core:rate-limit-exceeded` | Allowance exhausted - see [Rate limits](/docs/en/api-reference/rate-limits). |
| `503` | `mf-core:api-request-timeout` | The call exceeded the 30-second request limit. |
| `503` | `mf-core:rate-limiter-unavailable` | Rate limiting is temporarily unavailable - retry with backoff. |

**Each endpoint page documents its own codes** and status responses - for example
the `mf-core:tool-*` codes on the Tools endpoints.

## Authentication errors

`401` (no valid token) and `403` (missing scope or feature not enabled) use a
shorter envelope without `details`:

```json theme={null}
{ "error": "Authentication failed", "message": "Missing bearer token" }
```

```json theme={null}
{ "error": "Forbidden", "message": "Missing required scope: voice_agents:write" }
```

Here `error` is a short category, not a `mf-core:` code, and `message` is absent on
some `403` responses. See [Authorization](/docs/en/api-reference/authorization).

## Validation errors keyed by field

The **Voice Agents** endpoints and some **Voice Agent Settings** responses return
`422` with problems listed per field. `base` holds problems not tied to one field:

```json theme={null}
{
  "errors": {
    "name": ["is required"],
    "voice_config": ["unsupported keys: voice_config.foo"]
  }
}
```

A rejected settings update returns the settings response itself with `errors`
filled in and `values` and `revision` reflecting the unchanged state. The
[settings guide](/docs/en/api-reference/voice-agent-settings) shows the shape.

## Outbound call errors

The **Outbound Calls** endpoints predate the envelope and return:

```json theme={null}
{ "success": false, "error": "Description of the issue" }
```

Limit-related responses add a machine-readable `error_type`. The
[outbound guide](/docs/en/api-reference/outbound-calls) lists the status codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.