Skip to main content

​
Request & Response Handling

Understanding common request and response patterns will help you build robust integrations across all Telnyx services. This guide covers the universal HTTP concepts that apply to Voice, Messaging, Cloud Storage, IoT, and all other Telnyx APIs.

​
HTTP Methods

Telnyx APIs follow RESTful conventions using standard HTTP methods:

​
GET - Retrieve Resources

Used to fetch information without making changes: 
GET /v2/messaging_profiles
GET /v2/calls/{call_id}
GET /v2/storage/buckets

​
POST - Create Resources

Used to create new resources or trigger actions: 
POST /v2/calls          # Make a phone call
POST /v2/messages       # Send a message  
POST /v2/storage/objects # Upload a file

​
PATCH - Update Resources

Used to modify existing resources: 
PATCH /v2/messaging_profiles/{id} # Update profile
PATCH /v2/phone_numbers/{id}      # Update phone number settings

​
DELETE - Remove Resources

Used to delete resources: 
DELETE /v2/messaging_profiles/{id}     # Delete messaging profile
DELETE /v2/telephony_credentials/{id}  # Delete telephony credential

​
Request Format

​
Content-Type Headers

Most Telnyx APIs expect JSON payloads: 
Content-Type: application/json
For file uploads or form data: 
Content-Type: multipart/form-data
Content-Type: application/x-www-form-urlencoded

​
Request Structure

curl -X POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+1234567890",
    "from": "+0987654321", 
    "text": "Hello World"
  }' \
  "https://api.telnyx.com/v2/messages"

​
Response Format

​
Standard Response Structure

Most Telnyx APIs return JSON responses with consistent structure: 
{
  "data": {
    "id": "resource_id",
    "record_type": "resource_type",
    // ... resource properties
  },
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "total_pages": 5,
    "total_results": 100
  }
}

​
Success Responses

  • 200 OK: Request successful, data returned
  • 201 Created: Resource successfully created
  • 202 Accepted: Request accepted, processing asynchronously
  • 204 No Content: Request successful, no data to return

​
Error Responses

Error responses include details to help troubleshoot issues: 
{
  "errors": [
    {
      "code": "10001",
      "title": "Invalid parameter",
      "detail": "The 'to' field is required",
      "source": {
        "pointer": "/data/attributes/to"
      }
    }
  ]
}

​
Telnyx API Error Codes

For a comprehensive list of all Telnyx-specific error codes and their meanings, see the API Error Codes reference. This resource provides detailed explanations for each error code to help you troubleshoot and handle API errors effectively. Common error patterns include:
  • 10xxx codes: Parameter validation errors
  • 20xxx codes: Authentication and authorization errors
  • 30xxx codes: Resource not found or unavailable errors
  • 40xxx codes: Rate limiting and quota errors
  • 50xxx codes: Server-side errors

​
HTTP Status Codes

​
Client Errors (4xx)

  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: Authentication succeeded but access denied
  • 404 Not Found: Resource doesn’t exist
  • 422 Unprocessable Entity: Valid request format but logical errors
  • 429 Too Many Requests: Rate limit exceeded

​
Server Errors (5xx)

  • 500 Internal Server Error: Unexpected server error
  • 502 Bad Gateway: Upstream service error
  • 503 Service Unavailable: Service temporarily unavailable
  • 504 Gateway Timeout: Request timeout

​
Common Headers

​
Request Headers

Authorization: Bearer YOUR_API_KEY    # Authentication
Content-Type: application/json       # Request format
Accept: application/json             # Expected response format
User-Agent: YourApp/1.0             # Client identification

​
Response Headers

Content-Type: application/json      # Response format
X-RateLimit-Limit: 100             # Rate limit maximum
X-RateLimit-Remaining: 75          # Remaining requests
X-RateLimit-Reset: 1640995200      # Rate limit reset time

​
Pagination

For endpoints that return lists, Telnyx uses consistent pagination:

​
Request Parameters

GET /v2/messages?page[number]=2&page[size]=50

​
Response Metadata

{
  "data": [...],
  "meta": {
    "page_number": 2,
    "page_size": 50,
    "total_pages": 10,
    "total_results": 500
  }
}

​
Filtering and Sorting

​
Common Filter Patterns

# Filter by date range
GET /v2/messages?filter[created_at][gte]=2023-01-01

# Filter by status  
GET /v2/calls?filter[status]=completed

# Sort results
GET /v2/messages?sort=created_at
GET /v2/calls?sort=-created_at  # Descending order

​
Best Practices

​
Request Optimization

  • Use appropriate HTTP methods: Don’t use POST for retrieving data
  • Include relevant headers: Specify Content-Type and Accept headers
  • Validate input: Check parameters before sending requests
  • Handle timeouts: Set appropriate timeout values

​
Response Handling

  • Check status codes: Don’t assume all responses are successful
  • Parse error messages: Use error details for troubleshooting
  • Handle edge cases: Account for empty results and partial failures
  • Log appropriately: Log errors but avoid logging sensitive data

​
Next Steps

  • API Reliability & Retries - Handle failed requests
  • Webhook Fundamentals - Receive asynchronous notifications
  • API Glossary - Reference for API terminology