Docs/Help/Errors

Errors and retries

Every API error uses a consistent JSON structure and includes a request ID.

Error structure

JSON

{
  "success": false,
  "request_id": "req_example1234567890",
  "error": {
    "code": "invalid_token",
    "message": "Invalid or expired bearer token."
  }
}

Common errors

HTTP	Code	What to do
400	`missing_credentials`	Send both `api_key` and `api_secret`.
401	`invalid_credentials`	Check that the credentials belong to the selected environment.
401	`missing_token`	Add the Bearer token to the Authorization header.
401	`invalid_token`	Request a new token and retry once.
401	`inactive_api_key`	The API key is disabled. Contact Voyced.
403	`scope_denied`	The key lacks the required permission. Check capabilities or contact Voyced.
403	`customer_context_missing`	The key is not linked to a customer. Contact Voyced.
404	`not_found`	Check the endpoint path.
404	`number_not_found`	Use a number returned by the telephone-number list.
429	`rate_limited`	Wait, then retry with increasing delays.
5xx	`request_failed` or `server_error`	Record the request ID, retry safely and check service status.
502	`connection_test_failed`	The credentials worked, but the customer connection check did not pass. Keep the request ID and contact Voyced.
503	`balance_unavailable`	The call credit balance is not available for this customer profile. Do not treat this as a zero balance.
502	`follow_me_unavailable`	Voyced could not read Follow-Me for the number. Retry safely, then use the request ID if it continues.
503	`account_reference_unavailable`	Follow-Me cannot currently be read for that telephone number.

Safe retry rules

Do not retry 400 or 403 responses without changing the request or permissions.
For 401, request a new token and retry once.
For 429, wait before retrying and reduce the request rate.
For 5xx, use increasing delays and a retry limit.
Keep the Voyced request ID in your error log, but remove credentials and personal data.