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. |
ALLO_NUMBER_FORBIDDEN | You do not have access to this Allo line. List the lines you can access with GET /v2/api/numbers. |
NOT_NOTE_AUTHOR | Only the note’s author can edit or delete it. |
NOT_COMMENT_AUTHOR | Only the comment’s author can edit it. |
AGENT_TRANSFER_RULE_MEMBER_NO_LINE_ACCESS | The teammate a transfer rule points at has no access to this line. Pick one who does, from GET /v2/api/users. |
PARTNER_ACCESS_REQUIRED | This account is not an enabled partner. Partner access is granted by Allo, write to [email protected]. |
PARTNER_CONTRACT_CANNOT_PROVISION | Your partner contract does not allow creating or pricing accounts. Only Discounted licence (reseller) partners can. |
PARTNER_CANNOT_DEACTIVATE | Your partner contract does not allow deactivating this account. Only Discounted licence (reseller) partners can. |
RECORDING_ACCESS_DENIED | The user of this API key cannot play this call’s recording. Only the line owner, a team admin or manager, a member the line is shared with, or the recipient of a summary share can. Use a key of one of them. |
RECORDING_DOWNLOAD_RESTRICTED | The line belongs to a HIPAA-enabled team, so Allo creates no download link for its recordings. Listen to the recording in the Allo app. |
VIEW_PERMISSION_DENIED | Only the owner of a team view or a team ADMIN or MANAGER can update or delete it. |
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. |
INVALID_PARAMETER | A query parameter is malformed, for example pinned=yes instead of true or false. The parameter is named in param. |
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, so 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. |
SUMMARY_TEMPLATE_KEY_REQUIRED | The call has more than one completed summary template. Set template_key to disambiguate (e.g. MARKDOWN_CLASSIC or MARKDOWN_SHORT_CALL). |
EMPTY_NOTE_CONTENT | The note or comment content is empty. Provide a non-blank content value. |
NOTE_CONTENT_TOO_LONG | The note or comment content exceeds the maximum of 4,000 characters. Shorten the content. |
MISSING_ALLO_NUMBER_OR_SENDER_ID | Provide either allo_number (E.164 Allo line) or sender_id (sender-ID inbox). List your numbers with GET /v2/api/numbers. |
CONTACT_NOTES_UNAVAILABLE | Contact notes are not available for this workspace yet: it must be on the v2 contact model. Contact support if you believe this is an error. |
INVALID_THREAD_ENTITY_TYPE | Unknown entity_type value. Use one of: CALL, TEXT_MESSAGE, CONVERSATION_NOTE. |
UNKNOWN_FIELD | The request body carries a field the endpoint does not accept, named in param. Often a typo, or a read-only field such as custom_prompt. |
MISSING_FIELD | A required field is missing, named in param. Inside a collection it carries the index, for example transfer_rules[1].description. |
INVALID_PHONE_NUMBER | The phone number named in param could not be read. Use E.164 format, for example +14155551234. |
INVALID_TIMEZONE | Not an IANA timezone identifier. Use one such as Europe/Paris or America/New_York. |
INVALID_AGENT_LANGUAGE | Unknown AI receptionist language. The accepted values are listed in the message. |
INVALID_AGENT_CAPABILITY | Unknown capability key. Use SCHEDULING, CALL_TRANSFER or WARM_TRANSFER, in upper case. |
AGENT_TRANSFER_RULE_TARGET_REQUIRED | A transfer rule is missing the target its type requires: target_number, target_member_id or target_line_number. |
AGENT_NO_FORWARDING_NUMBER | Turning the AI receptionist off forwards calls to your business phone, and none is set on the workspace. |
AGENT_CALENDAR_TEAM_MISMATCH | The calendar belongs to another team. List the ones you can use with GET /v2/api/calendars. |
AGENT_CALENDAR_EVENT_TYPES_NOT_SUPPORTED | This calendar’s provider has no event types. Map it to an empty list. |
INVALID_KNOWLEDGE_URL | The URL has no public host. Send the URL of a publicly reachable site, for example https://example.com. |
PROMPT_SECTIONS_REQUIRED | sections was empty. It replaces the whole prompt, so it must carry every section to keep. |
INVALID_AGENT_PROMPT_SECTION | Unknown prompt section key. The accepted keys are listed in the message. |
DUPLICATE_AGENT_PROMPT_SECTION | A prompt section appears more than once. Send each at most once. |
INVALID_AGENT_PROMPT_SECTION_BODY | A prompt section carries the wrong body. required_fields takes fields, every other section takes content. |
MISSING_AGENT_PROMPT_SECTION | objective, personality and behaviors are required and one is missing or blank. |
AGENT_PROMPT_SECTION_TOO_LONG | A prompt section exceeds 3,000 characters. Shorten it. |
AGENT_PROMPT_TOO_LONG | The prompt rendered from all sections exceeds 25,000 characters. Shorten the sections. |
ATTRIBUTE_LABEL_INVALID | label is blank, longer than 255 characters, or has no letter or digit. |
ATTRIBUTE_KEY_RESERVED | The label resolves to the key of a built-in field, such as name, company or job_title for contacts, or name, website or industry for companies. Choose another label. |
ATTRIBUTE_OPTIONS_NOT_SUPPORTED | options was sent for an attribute that is not a dropdown. Send options only for DROPDOWN attributes. |
ATTRIBUTE_OPTION_INVALID | Every option needs a non-blank label of at most 255 characters, unique within the attribute, and a dropdown needs at least one option. |
ATTRIBUTE_BUILT_IN | The key is a built-in field, such as name or company, not a custom field. Built-in fields cannot be edited or deleted through the custom field endpoints. |
CUSTOM_ATTRIBUTE_KEY_UNKNOWN | custom_attributes has a key that is not an active custom attribute. List the keys with GET /v2/api/crm/attributes for people or GET /v2/api/crm/companies/attributes for companies. param is custom_attributes.<key>. |
CUSTOM_ATTRIBUTE_VALUE_INVALID | The value does not match the attribute type, for example a string for a NUMBER or a dropdown value that is not an option. Check the type, or send null to clear the value. param is custom_attributes.<key>. |
ESIM_NOT_AVAILABLE_IN_COUNTRY | number_preference.esim is true with a country other than FR. eSIM numbers are only available in France. |
INVALID_ESIM_TIER | Unknown eSIM tier. Use a code from GET /v2/api/partner/accounts/{account_id}/esims/offer. |
ESIM_IDENTITY_INCOMPLETE | The eSIM identity is missing or incomplete: corporate_name, postal_address, postal_code (5 digits) and city are required. |
INVALID_IDEMPOTENCY_KEY | The Idempotency-Key header must be 8 to 100 letters, digits, - or _. Send a UUID. |
INVALID_NUMBER_PREFERENCE | The country of the number preference is unknown or not supported. Send an ISO country code such as FR. |
INVALID_MEMBER_ROLE | Unknown member role. Use ADMIN, MANAGER or MEMBER. |
INVALID_FILTER_FIELD | A view filter field is neither a built-in person field nor the key of a custom field. List custom fields with GET /v2/api/crm/attributes. |
INVALID_FILTER_OPERATOR | A view filter operator does not match the type of its field. |
INVALID_FILTER_VALUE | A view filter value cannot be read for the type of its field. Use a numeric value for a number field and an ISO 8601 date such as 2026-01-31 or 2026-01-31T00:00:00Z for a date field. |
INVALID_SORT_FIELD | A view sort field is neither a built-in field nor a custom field key from GET /v2/api/crm/attributes. |
FIELD_NOT_SORTABLE | A view sort field exists but cannot be sorted on. Use a built-in sortable field or a sortable custom field. |
INVALID_REQUEST | The request is not valid as a whole. On GET /v2/api/conversations, send exactly one of allo_number or inbox_id, not both and not neither. |
INBOX_NAME_REQUIRED | An inbox needs a non-blank name. Send a short name such as Sales. |
INVALID_INBOX_SOURCE | A source is invalid: a null or invalid source, condition or digit, a menu path that is not in that line’s GET /v2/api/numbers/{number}/menu_options, two sources with the same allo_number, or a teammate inbox left with no line in the caller’s workspace. Menu conditions are only accepted on lines whose menu options list is not empty; on other lines use a whole-line source (empty conditions). To combine several options of one line, put all their paths in the branches of one MENU_BRANCH. |
INVALID_INBOX_FILTERS | The inbox filters have an unknown key or an invalid value. Accepted keys: types, user_ids (at most 50), contact_ids (at most 50), contact_list_ids (at most 10) and tag_keys (at most 20, each one a tag of your workspace). “Unread only” is not saved on an inbox: use the unread query parameter of GET /v2/api/conversations. |
INBOX_LIMIT_REACHED | The inbox owner already has 50 inboxes. Delete one with DELETE /v2/api/inboxes/{inbox_id}. |
FEATURE_NOT_SUPPORTED | Filtering conversations by the parameter named in param (inbox_id or pinned) is not available yet. List one line’s conversations with allo_number, without that parameter. |
CONTACT_FILTER_NOT_SUPPORTED | The inbox has saved contact filters, and this workspace is still on the old contact model, which cannot filter conversations by contact or contact list. Remove contact_ids and contact_list_ids from the inbox filters with PATCH /v2/api/inboxes/{inbox_id}. |
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. |
SUMMARY_TEMPLATE_NOT_FOUND | No completed summary exists for the requested template_key on this call. Fetch the call with GET /v2/api/conversations/items/{id} to see which summaries exist. |
ENDPOINT_NOT_FOUND | No endpoint found at this URL. Check the URL and HTTP method. See the API reference. |
PERSON_NOT_FOUND | No person found with this ID (per-*). Search people with POST /v2/api/crm/people/search. |
NOTE_NOT_FOUND | No note found with this ID. List a conversation’s notes with GET /v2/api/conversations/{contact_number}/notes. |
THREAD_NOT_FOUND | No thread found with this ID. Find an item’s thread with GET /v2/api/threads?entity_type=...&entity_id=.... |
THREAD_COMMENT_NOT_FOUND | No thread comment found with this ID. Fetch the thread with GET /v2/api/threads/{id} to see its comments. |
AGENT_VOICE_NOT_FOUND | No voice with this voice_id. List the catalog with GET /v2/api/voices. |
AGENT_KNOWLEDGE_NOT_FOUND | No knowledge entry of this kind with this ID for the line. List them with GET /v2/api/numbers/{number}/agent. |
AGENT_CALENDAR_NOT_FOUND | No calendar with this ID is visible to you. List them with GET /v2/api/calendars. |
PARTNER_ESIM_NOT_FOUND | No eSIM with this ID was ordered on an account your API key provisioned. Use the id returned by POST /v2/api/partner/accounts/{account_id}/esims. |
PARTNER_ESIM_NUMBER_NOT_FOUND | The phone number does not belong to this account. Use one of the account’s phone_numbers from GET /v2/api/partner/accounts/{id}. |
PARTNER_ESIM_HOLDER_NOT_FOUND | The holder_id user cannot hold an eSIM for this number. Leave holder_id out to make the account the holder. |
PARTNER_ACCOUNT_NOT_FOUND | No account with this ID was created by your API key, or the account is deactivated. You can only manage the accounts your own key created. |
RECORDING_NOT_FOUND | The call has no recording, or the ID is an SMS (msg-*). Only answered calls on lines with call recording on have one. |
ATTRIBUTE_NOT_FOUND | No attribute with this key, or it was deleted. List them with GET /v2/api/crm/attributes for people or GET /v2/api/crm/companies/attributes for companies. |
USER_HAS_NO_TEAM | owner_type is TEAM but the user does not belong to a team. Use USER. |
VIEW_NOT_FOUND | No view with this ID, or you cannot see it. List views with GET /v2/api/crm/views. |
INBOX_NOT_FOUND | No inbox with this ID for this user. Inboxes are personal: list them with GET /v2/api/inboxes, and add ?user_id= for a teammate’s. On GET /v2/api/conversations?inbox_id= right after a create, the error can be transient and carries retryable: true: retry once. On update or delete it is final. |
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. |
NUMBER_ALREADY_ASSIGNED | One or more phone numbers are already assigned to existing people. Set allow_duplicate_number to true to create anyway, or update the existing person with PUT /v2/api/crm/people/{id}. |
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. |
THREAD_ALREADY_EXISTS | The conversation item already has a thread (one thread per item). Find it with GET /v2/api/threads?entity_type=...&entity_id=... and add a comment with POST /v2/api/threads/{id}/comments. |
AGENT_KNOWLEDGE_ALREADY_EXISTS | The line already uses a website with this URL. Reuse the existing entry. |
AGENT_LINE_NOT_ASSIGNED | The line has no phone number assigned, so its AI receptionist can neither answer nor forward. |
ATTRIBUTE_KEY_CONFLICT | A custom field or attribute with this key already exists with another type. Choose another label, or reuse the existing one. |
ATTRIBUTE_SLOTS_EXHAUSTED | No free slot is left for custom fields or attributes of this type. Reuse an existing one or create one with another type. |
ATTRIBUTE_MANAGED_BY_INTEGRATION | The attribute is synced from a CRM integration and cannot be deleted. For companies, only prompt, should_prompt_override and is_visible can change. A person field cannot be edited at all. |
ATTRIBUTE_CONCURRENT_MODIFICATION | Attributes were modified at the same time. Retry the request. |
ESIM_NOT_ELIGIBLE | The number cannot carry an eSIM. Create the account with number_preference.esim set to true to get an eSIM number. |
ESIM_ALREADY_EXISTS | The number already has an eSIM. Read it with GET /v2/api/partner/esims/{id}. |
ESIM_ORDER_IN_PROGRESS | An eSIM order for this number is still provisioning. Always retryable: true. Wait for the partner.esim.ready or partner.esim.failed webhook. |
ESIM_ORDER_NEEDS_SUPPORT | A previous eSIM order for this number was charged but did not complete, and Allo support is handling it. Write to [email protected] before ordering again. |
ESIM_NOT_READY | The eSIM is not ready to install yet. Always retryable: true. Wait for the partner.esim.ready webhook, usually 5 to 15 minutes after the order. |
ESIM_SUBSCRIPTION_CONFLICT | The subscription you pay for this account cannot take an eSIM right now. When retryable is true, retry in a few minutes. Otherwise the subscription must be active, with no pending cancellation: write to [email protected]. |
PARTNER_ACCOUNT_ALREADY_EXISTS | The email or personal mobile, named in param, already belongs to an Allo account. Use another one. |
NO_NUMBER_AVAILABLE | No number matches the country and prefix you asked for. Nothing is charged. Retry later, or ask for another country or prefix. |
REGULATORY_VERIFICATION_REQUIRED | A number in this country needs the account’s regulatory verification first. Nothing is charged. Choose another country, or write to [email protected]. |
PARTNER_ACCOUNT_BUSY | Another number or member is being added to this account, or the same email is being added elsewhere. Always retryable: true: retry in a few seconds. |
IDEMPOTENCY_KEY_ALREADY_USED | An earlier attempt on this account already used this Idempotency-Key. Check the account with GET /v2/api/partner/accounts/{id} before you retry with a new key. |
PARTNER_ACCOUNT_DEACTIVATING | The account is being deactivated at the end of its billing period, so it takes no more numbers or members. |
PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT | The account’s subscription cannot be billed right now. When retryable is true, retry in a few minutes, once its pending invoice is settled. Otherwise write to [email protected]. |
PIN_LIMIT_REACHED | The user already has 10 pinned conversations. Unpin one with DELETE /v2/api/conversations/{contact_number}/pin first. |
Unprocessable errors (422)
| Code | Description |
|---|---|
CONTACT_FILTER_TOO_LARGE | The inbox’s contact filters resolve to too many phone numbers, or hold more than 50 contact IDs or 10 contact list IDs. The error type is validation_error. Narrow contact_ids and contact_list_ids with PATCH /v2/api/inboxes/{inbox_id}, or list by allo_number instead. |
Payment errors (402)
| Code | Description |
|---|---|
ESIM_PAYMENT_FAILED | Allo could not charge the eSIM to your card: declined, or a card that requires 3D Secure, which cannot be completed over the API. Nothing is left pending. Update your card in the partner portal, then retry with the same Idempotency-Key. Without a card and without enough prepaid credit, the error is PARTNER_CREDIT_INSUFFICIENT. |
PARTNER_CREDIT_INSUFFICIENT | Your prepaid credit does not cover this charge, and your billing account has no card on file to pay the rest. Nothing is created. Top up your credit or add a card, then retry. If the request carried an Idempotency-Key, send a new one. |
PARTNER_BILLING_FAILED | Allo could not charge your card, for example because it was declined. Nothing is created. Update your card, then retry. |
PARTNER_SUBSCRIPTION_NOT_BILLABLE | There is no subscription or billing account Allo can charge for this request. Write to [email protected]. |
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. |
AGENT_CALENDAR_EVENT_TYPES_FETCH_FAILED | The calendar provider could not be reached. Always retryable: true. If it persists, renew the calendar connection in the Allo app. |
ESIM_UNAVAILABLE | eSIMs cannot be ordered, or the activation code read, for this account right now. Write to [email protected] if it persists. |
PARTNER_BILLING_UNAVAILABLE | Billing is temporarily unavailable. Retry, with the same Idempotency-Key if you sent one: it resumes the same charge. |
PARTNER_NUMBER_SETUP_FAILED | The number could not be set up, and the charge was taken back. Not retryable: write to [email protected]. |
PARTNER_NUMBER_KEPT | The number was assigned but its setup did not complete. It stays on the account and on its billing. Not retryable, since a retry would add another number: write to [email protected] with the number. |
RECORDING_DOWNLOAD_UNAVAILABLE | The recording download link could not be created. Always retryable: true: retry in a few seconds. |