Skip to main content
All API errors follow a consistent format designed for both developers and AI agents.

​
Error response format

{
  "error": {
    "type": "not_found_error",
    "code": "CONVERSATION_ITEM_NOT_FOUND",
    "message": "No call or message found with ID 'cll_abc123'.",
    "retryable": false,
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://help.withallo.com/en/v2/api-reference/guides/error-handling#CONVERSATION_ITEM_NOT_FOUND",
    "param": "id",
    "suggestion": "Search for the item using POST /v2/api/conversations/items/search."
  }
}

​
Error fields

FieldTypeDescription
typestringError category (see table below)
codestringStable error code for programmatic handling
messagestringHuman-readable explanation including the value that failed
retryablebooleanWhether the request can be retried
request_idstringUnique ID for this request — include in support tickets
doc_urlstringLink to documentation about this error
paramstringThe parameter that caused the error (if applicable)
suggestionstringWhat to do next (may include endpoint names)
errorsarrayField-level errors for validation failures
retry_after_secondsintegerSeconds to wait before retrying (rate limits only)

​
Error types

TypeHTTP StatusWhen
authentication_error401Invalid, missing, or expired API key
permission_error403Valid key but insufficient scope
validation_error400Bad input, missing params, wrong format
not_found_error404Resource doesn’t exist
conflict_error409Duplicate or state conflict
rate_limit_error429Too many requests (always retryable: true)
server_error500Internal failure

​
Request ID

Every response includes a request_id (format: req_ + 12 alphanumeric characters). You can also send your own via the X-Request-Id header — the API will use it instead of generating one. 
curl -X GET "https://api.withallo.com/v2/api/conversations" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "X-Request-Id: req_my_custom_id"

​
Validation errors

When multiple fields fail validation, the errors array lists each one: 
{
  "error": {
    "type": "validation_error",
    "code": "INVALID_REQUEST",
    "message": "Request validation failed.",
    "errors": [
      { "field": "date_from", "code": "INVALID_DATE", "message": "Must be a valid ISO 8601 date." },
      { "field": "allo_number", "code": "INVALID_PHONE_FORMAT", "message": "Must be E.164 format (e.g. +14155551234)." }
    ]
  }
}

​
Phone number format

All phone numbers must be in E.164 format: + followed by country code and number, no spaces or dashes. 
+14155551234    ← correct
0612345678      ← wrong (missing country code)
+33 6 12 34 56  ← wrong (contains spaces)
Invalid phone numbers return: 
{
  "error": {
    "type": "validation_error",
    "code": "INVALID_PHONE_FORMAT",
    "message": "'+33 6 12 34' is not a valid E.164 phone number.",
    "suggestion": "Use E.164 format: +14155551234 (no spaces, with country code)."
  }
}

​
Idempotency

All write endpoints (POST, PUT, DELETE) support an optional Idempotency-Key header to safely retry requests.

​
How it works

  1. Send a unique Idempotency-Key header with your write request (e.g., a UUID)
  2. If the request succeeds (2xx), the response is stored for 1 hour
  3. If you send the same key again to the same endpoint, the API returns the stored response with an Idempotency-Replayed: true header — the operation is not re-executed
  4. If the request fails (4xx/5xx), the key is not consumed — you can retry with the same key until the request succeeds

​
Example

# First request — executes the operation
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# → 200 OK, Idempotency-Key: 550e8400-...

# Retry — returns stored response without re-executing
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# → 200 OK, Idempotency-Replayed: true

​
Key reuse across endpoints

Using the same idempotency key for a different endpoint or HTTP method returns a 409 error with code IDEMPOTENCY_KEY_REUSE.

​
Response headers

HeaderDescription
Idempotency-KeyEchoed back on all requests that include the header
Idempotency-ReplayedSet to true when the response is replayed from cache

​
Error code reference

See the Error codes catalog for a complete list of all error codes with recovery instructions.