Error Codes

The Telephony.io API uses standard HTTP status codes to indicate the success or failure of API requests. All error responses include a JSON body with additional details.

Error Response Format

When an error occurs, the API returns a JSON object with an error message and a machine-readable code:

{
  "error": "Invalid phone number format",
  "code": "invalid_parameter"
}

HTTP Status Codes

200 - OK

The request was successful. The response body contains the requested data.

400 - Bad Request

The request was invalid or cannot be served. This is often due to missing or invalid parameters. Check the error message for specific details.

Common causes:

  • Missing required parameters
  • Invalid phone number format
  • Invalid verification code length

401 - Unauthorized

Authentication failed. Your API key is either missing, invalid, or has been revoked. Check that you're including the correct API key in the Authorization header.

Authorization: Bearer sk_live_your_api_key_here

402 - Payment Required

Insufficient wallet balance. This error occurs when your account doesn't have enough credits to complete the requested operation.

To resolve this error, you must top up your account balance via the Dashboard. Telephony.io operates on a pre-paid model, and all API calls deduct credits from your wallet in real-time.

Example response:

{
  "error": "Insufficient credits to complete this request",
  "code": "insufficient_balance",
  "required_credits": 1.50,
  "current_balance": 0.25
}

429 - Too Many Requests

You've exceeded the rate limit for your account. Rate limits help ensure fair usage and system stability.

Wait a moment before retrying your request. The response includes a Retry-After header indicating how long to wait (in seconds).

500 - Internal Server Error

Something went wrong on our end. These errors are logged and investigated by our team. If the problem persists, please contact support with the error details.

Best Practices

  • Monitor your balance: Check your wallet balance regularly to avoid 402 errors interrupting your service
  • Implement retry logic: Handle transient errors (429, 500) with exponential backoff
  • Log error responses: Store error codes and messages for debugging
  • Validate inputs: Check parameters client-side before making API calls to reduce 400 errors