Errors

Verified against backend/internal/publicapi/errors.go and webhook_error_class.go.

The error envelope

Every non-2xx response from /api/v1/ext/* has the same shape — an error object, not a flat string. This deliberately matches the convention OpenAI and Anthropic use, because that's the shape a generated SDK and a model writing client code both reach for first:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "phone_number_id is required",
    "hint": "",
    "fields": [
      { "field": "phone_number_id", "reason": "is required" }
    ]
  }
}

Field names are yours, not ours

Validation errors name the field the way you sent it. Earlier versions of this API returned the Go validator's raw output:

Key: 'BindPhoneNumberRequest.PhoneNumberID' Error:Field validation for 'PhoneNumberID' failed on the 'required' tag

— a Go type name, Go field name, and struct-tag name, handed to a caller who sent JSON and has never seen any of those three symbols. That's fixed: every field error is now translated back to the JSON key you actually used.

Error codes — the complete set

Every code the public surface can return: 53, read out of the handlers and middleware behind /api/v1/ext on origin/main (2026-08-25). code is stable; message and hint may be reworded. Where one code is used with two statuses, both are listed. An earlier version of this page listed seven and called the set open — it is closed, and this is it.

Authentication and scopes (middleware/api_key_auth.go)

Versioning (middleware/api_version.go)

Rate limits and quotas

Idempotency and request body (middleware/idempotency.go)

Generic

Agents (publicapi/agents_handler.go, agents_write_handler.go)

Calls and leads (calls_handler.go, leads_handler.go)

Knowledge (knowledge_handler.go)

Phone numbers (phonenumbers_handler.go, phonenumbers_acquire*.go)

Webhooks (webhooks_handler.go)

Call control (callcontrol_handler.go)

A known rough edge

A 404 (route or resource not found — e.g. a typo'd webhook URL, or an ID that doesn't exist) currently classifies the same way as a 400/422 (bad payload) in the webhook delivery error-class system described below. That means a customer with a typo in their webhook destination URL gets pointed at their payload, not their URL, when a delivery bounces. Stated here because it's real and unresolved, not because it's been fixed.

Webhook delivery error classes

Separately from the request/response error envelope above, every webhook delivery attempt that doesn't succeed is classified into one of these, visible on the delivery-log entry (GET /webhooks/:id/deliveries). The classes exist because "failed" isn't diagnosable, and four very different situations were all landing in one bucket before this existed.

Ours — something on VoiceMatrix's side of the wire:

Theirs — the destination answered, and said no:

internal covers anything that doesn't match a known pattern — an honest "we don't know" rather than silently absorbing it into an unrelated bucket.

Why this distinction matters in practice: a real production incident had 43 deliveries fail with no response at all. The customer-facing story would have been "your endpoint is broken" — the actual cause was VoiceMatrix's own reachability guard declining to dial the address. Those 43 counted toward the auto-pause threshold and left two customer webhooks paused with the wrong diagnosis attached. The class field is what lets the UI (and you) tell "your server is down" apart from "we wouldn't call your server."

Next

• Webhooks — delivery, retries, replay, and where these classes surface
• Authentication — scopes and the requests that produce INSUFFICIENT_SCOPE