Error Codes

Every non-2xx response from the DialStack REST API shares the same shape:

{
  "error": "Human-readable message describing what went wrong.",
  "code": "machine_readable_code",
  "details": { "field_name": "reason" }
}

error is always present. code is present on errors that have a stable machine-readable identifier (listed below). details is optional and carries field-level validation context when applicable.

info

Branch on code, not on error. The error string may be rephrased without notice; code values are stable and versioned. When no code is present, fall back to the HTTP status.

HTTP status codes

Status	Meaning	Retry?
400	Malformed request — invalid JSON, missing required fields.	No — fix the request.
401	Missing or invalid API key (Authorization: Bearer ...).	No — rotate / check the key.
403	Valid key, but no access to this account or resource.	No — check DialStack-Account.
404	Resource does not exist on this account.	No.
409	Conflict — e.g., duplicate handle, already assigned.	No.
422	Validation error — payload is well-formed but semantically wrong.	No — fix the payload.
429	Rate limit exceeded. Retry-After header tells you when to retry.	Yes, after Retry-After.
5xx	Server error. Transient unless documented otherwise.	Yes, with exponential backoff.

Stable error codes

The following code values are stable and safe to branch on. Codes not listed here are either legacy or platform-internal; do not rely on them.

Code	HTTP	Meaning
validation_error	400	The request body failed validation. See details for field-level reasons.
invalid_pagination	400	The pagination cursor is malformed or expired. Restart from the first page.
invalid_sandbox_phone_number	400	The supplied phone number is not a valid sandbox number for this platform.
sandbox_feature_unsupported	400	The requested feature is not available in sandbox mode for this platform.

Device provisioning

Code	HTTP	Meaning
unsupported_vendor	400	The phone vendor/model is not supported for provisioning.
invalid_configuration	400	The provisioning request is missing required device fields.
credentials_not_found	404	No SIP credentials exist for this endpoint.
generation_failed	500	The provisioning file could not be generated. Safe to retry.

Handling errors

• Treat missing code as an unstable error. Log the error string for debugging, but make a business decision off HTTP status alone.
• Do not parse the error string. It is subject to i18n and rephrasing.
• On 429, respect Retry-After. Typical values are small (≤ 60s).
• On 5xx, use exponential backoff. Start at 1s, double up to ~60s, cap at ~5 attempts. Every DialStack mutation is keyed by an operation ID so retries are safe — idempotency is built into the API.