Error Handling

All API errors follow a consistent format, making it easy to handle them programmatically.

Error Response Format

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Codes Reference

Client Errors (4xx)

Code	HTTP Status	Description
`invalid_parameters`	400	Missing or invalid request parameters
`already_linked`	400	Resource is already linked
`already_in_use`	400	Resource is being used elsewhere
`no_phone_number`	400	No phone number to operate on
`invalid_status`	400	Resource is in wrong status for operation
`insufficient_credits`	402	Not enough credits for operation
`forbidden`	403	You don't have permission
`not_found`	404	Resource not found
`rate_limit_exceeded`	429	Too many requests

Server Errors (5xx)

Code	HTTP Status	Description
`database_error`	500	Database operation failed
`provider_error`	500	External provider (Telnyx) error
`server_error`	500	Unexpected server error

Error JSON Schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_parameters",
            "already_linked",
            "already_in_use",
            "no_phone_number",
            "invalid_status",
            "insufficient_credits",
            "forbidden",
            "not_found",
            "rate_limit_exceeded",
            "database_error",
            "provider_error",
            "server_error"
          ],
          "description": "Error code for programmatic handling"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message"
        },
        "details": {
          "type": "object",
          "description": "Additional error details (field-specific validation errors)"
        }
      },
      "required": ["code", "message"]
    }
  }
}

Handling Validation Errors

When code is invalid_parameters, the details object contains field-specific errors:

{
  "error": {
    "code": "invalid_parameters",
    "message": "Validation failed",
    "details": {
      "phone_number": "Invalid phone number format",
      "city": "City is required"
    }
  }
}

Best Practices

Always check the code field for programmatic error handling

Display the message field to users for human-readable feedback

Log the full error response for debugging

Implement retry logic for rate_limit_exceeded and transient server_error

Handle insufficient_credits by prompting users to purchase more credits

Errors

Error Handling#

Error Response Format#

Error Codes Reference#

Client Errors (4xx)#

Server Errors (5xx)#

Error JSON Schema#

Handling Validation Errors#

Best Practices#