Errors

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:

{
  "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.
`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:

{ "error": "Authentication failed", "message": "Missing bearer token" }

{ "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.

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:

{
  "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 shows the shape.

Outbound call errors

The Outbound Calls endpoints predate the envelope and return:

{ "success": false, "error": "Description of the issue" }

Limit-related responses add a machine-readable error_type. The outbound guide lists the status codes.

Get started

Voice Agents

Voice Agent Settings

Tools

Outbound Calls

Conversations

Evals

The error envelope

Authentication errors

Validation errors keyed by field

Outbound call errors

​The error envelope

​Authentication errors

​Validation errors keyed by field

​Outbound call errors

The error envelope

Authentication errors

Validation errors keyed by field

Outbound call errors