Error Handling

TryVox uses conventional HTTP status codes and structured error responses to indicate the success or failure of API requests.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid phone number format",
    "details": [
      {
        "field": "to",
        "reason": "must be E.164 format"
      }
    ]
  }
}

Error Object Fields

• code — Machine-readable error code (see table below)
• message — Human-readable error description
• details — (Optional) Array of validation errors or additional context

Error Codes

TryVox uses the following error codes:

Common Errors

Validation Errors (400)

Returned when request parameters are invalid or missing required fields.

Example:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "field": "to",
        "reason": "must be E.164 format (e.g., +14155551234)"
      },
      {
        "field": "from",
        "reason": "required field missing"
      }
    ]
  }
}

Authentication Errors (401)

Returned when the API key is missing, invalid, or expired.

Example:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Fix: Check that you're including the Authorization: Bearer <api_key> header with a valid API key.

Permission Errors (403)

Returned when your API key doesn't have permission to access the requested resource.

Example:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource"
  }
}

Resource Not Found (404)

Returned when the requested resource doesn't exist.

Example:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Call with UUID 'abc123' not found"
  }
}

Verification Errors (422)

Returned when verification code check fails (Verify API).

Example:

{
  "error": {
    "code": "VERIFICATION_FAILED",
    "message": "Invalid verification code"
  }
}

Rate Limiting (429)

Returned when you exceed the rate limit for your API key.

Example:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Response Headers:

Rate-limited responses include a Retry-After header indicating when you can retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Fix: Implement exponential backoff and respect the Retry-After header.

Delivery Failures (502)

Returned when TryVox successfully processed your request but the upstream carrier or delivery channel failed.

Example:

{
  "error": {
    "code": "DELIVERY_FAILED",
    "message": "Carrier rejected the call"
  }
}

This typically happens with invalid phone numbers, blocked destinations, or carrier issues.

Internal Errors (500)

Returned when TryVox encounters an unexpected internal error.

Example:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again."
  }
}

Fix: Retry the request with exponential backoff. If the issue persists, contact support@tryvox.io.

Rate Limiting

API requests are rate-limited per API key to ensure fair usage and system stability.

Default Limits

• Voice API: 100 requests per minute
• Verify API: 50 requests per minute
• Numbers API: 20 requests per minute

Handling Rate Limits

When you receive a 429 RATE_LIMITED response:

1. Check the Retry-After header for the wait time (in seconds)
2. Wait the specified duration before retrying
3. Implement exponential backoff for subsequent retries

Example (Python):

import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get('Retry-After', 60))
        time.sleep(retry_after)

    return response

Increasing Rate Limits

Need higher rate limits? Contact sales@tryvox.io to discuss enterprise plans.

Best Practices

1. Always check HTTP status codes before parsing response bodies
2. Handle all error codes gracefully with appropriate user feedback
3. Log error details for debugging and monitoring
4. Implement retry logic with exponential backoff for transient errors (429, 500, 502)
5. Validate inputs client-side to reduce validation errors
6. Monitor error rates to catch issues early

Next Steps

• Set up webhooks to handle asynchronous events
• Explore the Voice API to make calls
• Learn VoxML to control call flow