Documentation Index
Fetch the complete documentation index at: https://help.withallo.com/llms.txt
Use this file to discover all available pages before exploring further.
Every error response includes a stable code field. The doc_url in each error links directly to the relevant entry below. Codes are stable contracts — they will not change without an API version bump.
Authentication errors — 401
| Code | Description |
|---|
API_KEY_INVALID | The API key provided is invalid or does not exist. Check your API key in Settings > API. |
API_KEY_REVOKED | This API key has been revoked. Create a new API key in Settings > API. |
UNAUTHORIZED | Authentication is required. Provide a valid API key in the Authorization header as Api-Key <your-key>. |
Permission errors — 403
| Code | Description |
|---|
API_KEY_INSUFFICIENT_SCOPE | This API key lacks the required scope. Create a new key with the required scope. See scope-to-endpoint mapping. |
API_KEY_TRIAL_NOT_ALLOWED | API access is not available on trial plans. Upgrade to a paid plan. |
FORBIDDEN | You do not have permission to perform this action. Contact your workspace admin. |
A2P_NOT_ENABLED | A2P (Application-to-Person) SMS is not enabled for this number. Complete 10DLC registration in the Allo dashboard. |
Validation errors — 400
| Code | Description |
|---|
INVALID_REQUEST_BODY | The request body could not be parsed. Ensure Content-Type is application/json and the body is well-formed JSON. |
MISSING_PARAMETER | A required query parameter is missing. Add the parameter named in the param field. |
MISSING_HEADER | A required header is missing. Add the header named in the param field. |
UNSUPPORTED_MEDIA_TYPE | The Content-Type is not supported. Use application/json. Returns 415. |
INVALID_PAGE_SIZE | The size parameter value is invalid. Provide a numeric value between 1 and 100. |
INVALID_SEARCH_QUERY | The search parameter must contain at least one alphanumeric character. Special characters are stripped automatically — provide plain-text keywords (e.g., "john" or "missed call"). Words are combined with AND and prefix-matched. |
MISSING_ALLO_NUMBER | The allo_number parameter is required. Add it to your request. List your numbers with GET /v2/api/numbers. |
INVALID_DATE_RANGE | The date range is invalid: from must be before to. Use YYYY-MM-DD format. |
DATE_RANGE_TOO_WIDE | The date range exceeds the maximum allowed number of days. Narrow your date range. |
INVALID_ITEM_ID | Item ID has an unrecognized prefix. Use IDs from the conversations API: cll- for calls, msg- for messages. |
BATCH_TOO_LARGE | Batch size exceeds the maximum of 100. Split your request into batches of 100 or fewer. |
TAGS_REQUIRED | At least one tag is required. Provide a non-empty tags array. List available tags with GET /v2/api/tags. |
INVALID_ACTION | Unknown action value. Use one of: READ, UNREAD, ARCHIVE, UNARCHIVE. |
INVALID_GRANULARITY | Unknown granularity value. Use one of: DAY, WEEK, MONTH. |
INVALID_GROUP_BY | Unknown group_by value. Check the suggestion field for allowed values. |
UNSUPPORTED_EXTEND_VALUE | Unknown extend value. Currently supported: transcript. |
METHOD_NOT_ALLOWED | HTTP method not supported for this endpoint. Check the suggestion field for supported methods. Returns 405. |
INVALID_PHONE_FORMAT | Phone number is not valid E.164 format. Use format: +14155551234 (+ prefix, country code, no spaces or dashes). |
INVALID_TO_NUMBER | The destination number is invalid or cannot be reached. Provide a valid E.164 phone number. |
TO_NUMBER_COUNTRY_MISMATCH | Cross-country SMS is not supported for this number. Use a phone number in the same country as the recipient. |
NUMBER_NOT_SMS_ENABLED | This number does not have outbound SMS enabled. Enable SMS in the dashboard, or use a different number from GET /v2/api/numbers. |
SENDER_ID_INBOX_CANNOT_SEND_SMS | Sender ID inboxes cannot send SMS messages. Use a regular phone number instead. |
SENDER_ID_NOT_ACTIVE | The sender ID is not active. Activate the sender ID in the Allo dashboard before sending. |
MESSAGE_NOT_COMPLIANT | Message content does not comply with messaging compliance rules. Remove disallowed content and retry. |
LANDLINE_NUMBER_NOT_SUPPORTED | The destination number is a landline and cannot receive SMS. Provide a mobile phone number instead. |
Not found errors — 404
| Code | Description |
|---|
CONVERSATION_ITEM_NOT_FOUND | No call or message found with this ID. Search for the item with POST /v2/api/conversations/items/search. |
MEMBER_NOT_FOUND | No team member found with this ID. List team members with GET /v2/api/users. |
TEAM_NOT_FOUND | No team found for the authenticated user. Check team setup in the Allo dashboard. |
USER_NOT_FOUND | The authenticated user account was not found. Verify the API key is associated with an active account. |
BUSINESS_NOT_FOUND | No business account found for the authenticated user. Ensure the account has completed onboarding. |
CALL_NOT_FOUND | No call found with this ID. Search calls with POST /v2/api/conversations/items/search. |
TEXT_MESSAGE_NOT_FOUND | No text message found with this ID. Search messages with POST /v2/api/conversations/items/search. |
PHONE_NUMBER_NOT_FOUND | No phone number found for your account. List your numbers with GET /v2/api/numbers. |
FROM_NUMBER_NOT_FOUND | No Allo phone number found for your account. List your available numbers with GET /v2/api/numbers. |
TAG_NOT_FOUND | The tag does not exist on this conversation item. It may have already been removed. |
SENDER_ID_NOT_FOUND | No active sender ID found. Check your sender IDs in the Allo dashboard. |
ENDPOINT_NOT_FOUND | No endpoint found at this URL. Check the URL and HTTP method. See the API reference. |
Conflict errors — 409
| Code | Description |
|---|
TAG_ALREADY_EXISTS | This tag is already applied to the conversation item. No action needed. |
OTHER_TRANSACTION_IN_PROGRESS | Another operation on this resource is in progress. Wait a moment and retry. |
IDEMPOTENCY_KEY_REUSE | This idempotency key was already used for a different endpoint or HTTP method. Use a unique key per distinct request. See Idempotency. |
Rate limit errors — 429
| Code | Description |
|---|
RATE_LIMIT_EXCEEDED | Per-second rate limit exceeded. Always retryable: true. Wait retry_after_seconds before retrying. |
TRIAL_SMS_LIMIT_REACHED | Trial account daily SMS limit reached. Upgrade your plan to send more messages. |
SMS_LIMIT_REACHED | Daily API SMS limit reached. Wait until tomorrow or contact support to increase your limit. |
DAILY_SMS_LIMIT_REACHED | Daily SMS limit reached for this number. Wait until tomorrow to send more messages from this number. |
Server errors — 500
| Code | Description |
|---|
INTERNAL_SERVER_ERROR | An unexpected error occurred. Retry the request. If it persists, contact [email protected] with your request_id. |
