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/calls/{call_id}     # Update call settings
PATCH /v2/messaging_profiles/{id} # Update profile

DELETE - Remove Resources ​

Used to delete resources:

DELETE /v2/calls/{call_id}    # Hang up a call
DELETE /v2/storage/objects/{key} # Delete a file

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"
      }
    }
  ]
}

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