Skip to main content

​
Error envelope

All errors follow a consistent format: 
{
  "error": {
    "code": "validation_error",
    "message": "caller_id must be E.164 format",
    "fields": {
      "caller_id": "Expected +<country><number>"
    }
  }
}

​
Error codes

CodeHTTP StatusDescription
validation_error400Request body or parameters are invalid
unauthorized401Missing or invalid API key
forbidden403API key does not have access to this resource
not_found404The requested resource does not exist
idempotency_conflict409A request with this Idempotency-Key already succeeded
caller_id_not_verified422The caller ID is not verified for your account
internal_error500An unexpected server error occurred

​
Idempotency

The POST /voice/calls endpoint supports idempotent requests. Include an Idempotency-Key header with a unique UUID to prevent duplicate calls on retry. 
curl -X POST https://api.247calldesk.com/api/v1/voice/calls \
  -H "Authorization: Bearer calldesk_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"caller_id": "+14155550123", "destination": "+14155559876"}'
If the same key is used again, the API returns 409 Conflict with a reference to the original call.