#Error codes

Every error response has this shape; branch on code (stable, never renamed), show message to humans, and quote request_id when asking for support.

{ "error": { "code": "DESTINATION_NOT_ALLOWED", "message": "Calls to US are not allowed", "details": { "country": "US" }, "request_id": "5f0c7c9e-..." } }

Code	HTTP	Meaning
`VALIDATION_FAILED`	400	The request body, query or path parameters are invalid.
`UNAUTHENTICATED`	401	Missing or invalid API key or session.
`FORBIDDEN`	403	The API key lacks the scope required for this operation.
`NOT_FOUND`	404	The resource does not exist.
`CONFLICT`	409	The request conflicts with the current state of the resource.
`IDEMPOTENCY_KEY_REUSED`	409	The Idempotency-Key was already used with a different request body.
`INVALID_STATE`	409	The operation is not allowed in the resource's current state.
`CAPABILITY_NOT_SUPPORTED`	422	The carrier behind this resource does not support the operation. Check /v1/carriers/{id} capabilities.
`CALLER_ID_NOT_OWNED`	422	The caller ID is not an active number in this workspace.
`DESTINATION_NOT_ALLOWED`	422	The destination country or prefix is not allowed by the workspace limits.
`INVALID_PHONE_NUMBER`	422	The phone number is not a valid E.164 number.
`AGENT_NOT_REGISTERED`	422	The agent has no active SIP registration, so it cannot be rung.
`LIMIT_EXCEEDED`	429	A workspace limit (agents, concurrent calls, calls per hour/day) was reached.
`SPEND_GUARD_TRIPPED`	429	Outbound calling is stopped by the spend guard. An admin must review usage and reset it.
`RATE_LIMITED`	429	Too many API requests. Retry after the time in the Retry-After header.
`CARRIER_ERROR`	502	The carrier API returned an error. Details contain the normalized reason.
`CARRIER_AUTH_FAILED`	422	The carrier rejected the supplied credentials.
`CARRIER_UNAVAILABLE`	503	The carrier is disabled, revoked or unhealthy.
`SWITCH_UNAVAILABLE`	503	The call controller or FreeSWITCH is not reachable.
`INTERNAL_ERROR`	500	Unexpected server error. Retry with the same Idempotency-Key.

Retry guidance: 429 → wait Retry-After; 503 SWITCH_UNAVAILABLE / CARRIER_UNAVAILABLE and 500 → retry with backoff and the same Idempotency-Key; 4xx validation/policy errors → fix the request.