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. |
FAX_NOT_AVAILABLE | Faxing is not available for this account. Contact Allo support to get it enabled. |
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. |
ACCOUNT_SUSPENDED | The account is suspended, so it cannot send SMS until it is resumed. Ask the account's provider to resume it, then retry. Partners resume an account with POST /v2/api/partner/accounts/{id}/resume. |
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. |
FAX_NOT_SUPPORTED_ON_NUMBER | The from line cannot send faxes. Only US and Canada local numbers can, not toll-free numbers or sender IDs. Pick another line from GET /v2/api/numbers. |
FAX_NOT_ENABLED_ON_LINE | Fax is turned off on the from line. Turn on Send and receive faxes in the number settings in the Allo app, or use another line. |
FAX_FILE_NOT_PDF | The fax file is not a PDF. Send the document as a PDF with content type application/pdf. |
FAX_FILE_EMPTY | The fax file is empty. Attach a non-empty PDF in the file part. |
MAX_UPLOAD_SIZE_EXCEEDED | The uploaded file is too large. A fax file can be at most 12 MB: compress the PDF or split it into several faxes. |
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. |
INVALID_ESIM_TOPUP | Unknown eSIM top-up, named in param (code). Use a top_ups[].code from GET /v2/api/partner/accounts/{account_id}/esims/offer. |
PARTNER_ACCOUNT_OWNER_NOT_REMOVABLE | The account itself is not a member and cannot be removed from its workspace. To end the account, use DELETE /v2/api/partner/accounts/{id}. |
PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT | Both phone_number and number_preference were sent. Send phone_number to hand over a number the account holds, or number_preference for a new one. |
ESIM_IDENTITY_INCOMPLETE | The eSIM identity is missing or incomplete: corporate_name, postal_address, postal_code (5 digits) and city are required. |
SENDER_ID_INVALID_FORMAT | The sender_id must be 1 to 11 letters or digits, with no spaces or symbols, for example MYBRAND. |
EXAMPLE_CONTENT_TOO_LONG | The example_content of the sender ID is longer than 1,000 characters. Shorten it. |
INVALID_IDEMPOTENCY_KEY | The Idempotency-Key header must be 8 to 100 letters, digits, - or _. Send a UUID. |
IDEMPOTENCY_KEY_REQUIRED | This request needs an Idempotency-Key header, named in param, so a retry cannot charge twice. Required on POST /v2/api/partner/esims/{id}/topups. Send a UUID, and the same one when you retry. |
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_SENDER_ID_NOT_FOUND | No sender ID with this ID is declared on this account. List them with GET /v2/api/partner/accounts/{account_id}/sender_ids. |
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. |
PARTNER_ACCOUNT_MEMBER_NOT_FOUND | No member with this ID is in the account's workspace. List the account's members with GET /v2/api/partner/accounts/{id}/members. |
PARTNER_ACCOUNT_NUMBER_NOT_FOUND | The account does not hold this phone_number itself: the number is not on the account, or a member holds it. Use a number listed by GET /v2/api/partner/accounts/{id} that no member of GET /v2/api/partner/accounts/{id}/members holds. |
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 that is not revoked. Read it with GET /v2/api/partner/esims/{id}, or revoke it with POST /v2/api/partner/esims/{id}/revoke to order a new one. |
PARTNER_ESIM_NOT_REVOCABLE | The eSIM is not live: it is still being set up, it failed, or it is being moved between the network and the eSIM. Only an ACTIVE eSIM can be revoked. Check its status with GET /v2/api/partner/esims/{id}. |
PARTNER_ESIM_MOVE_IN_PROGRESS | One of the member's eSIMs is being moved between the network and the eSIM right now, so the member cannot be removed yet. Always retryable: true: retry in a few minutes. |
PARTNER_ESIM_MOVE_FAILED | One of the member's eSIMs failed to move between the network and the eSIM, so it cannot be revoked and the member cannot be removed yet. Contact Allo support: the eSIM needs a manual check. |
PARTNER_ESIM_REVOKED | The eSIM was revoked, so its activation code is no longer available. To give the number a new eSIM, order one. |
PARTNER_NUMBER_HAS_LIVE_ESIM | The phone_number still has an eSIM that is not revoked. Revoke it with POST /v2/api/partner/esims/{id}/revoke, then hand the number over. |
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 still provisioning, so its activation code cannot be read and its tier and data cannot be changed yet. Always retryable: true. Wait for the partner.esim.ready webhook, usually 5 to 15 minutes after the order. |
ESIM_NOT_ACTIVE | The eSIM was deleted, or the number has a newer eSIM order: only the number's latest eSIM can have its tier and data changed. Use the latest eSIM's id, or order a new eSIM with POST /v2/api/partner/accounts/{account_id}/esims. |
ESIM_TIER_CHANGE_CONFLICT | A downgrade is already scheduled for this eSIM, and it cannot be replaced until it applies. GET /v2/api/partner/esims/{id} returns it in scheduled_tier and scheduled_tier_at. Retry after that date. |
ESIM_TOPUP_PENDING | Another top-up for this eSIM is still being paid. Always retryable: true. Retry in a few minutes, or retry the earlier request with its Idempotency-Key to resume it. |
ESIM_SUBSCRIPTION_CONFLICT | The subscription you pay for this account cannot be charged for eSIMs right now. The message gives the reason. When retryable is true, retry in a few minutes. Otherwise the subscription must be active, with no pending cancellation: write to [email protected]. |
SENDER_ID_ALREADY_EXISTS | The sender ID already belongs to another Allo account. A sender ID belongs to one account only: choose another name. |
MAX_SENDER_IDS_REACHED | The account already has 3 sender IDs, the maximum. List them with GET /v2/api/partner/accounts/{account_id}/sender_ids. |
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 or removed from 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. On POST /v2/api/partner/esims/{id}/topups, the key was already used for a top-up with another code on this eSIM: send a new Idempotency-Key for a new top-up. |
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 order, tier upgrade or top-up to your card: declined, or a card that requires 3D Secure, which cannot be completed over the API, so the attempt is cancelled. 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. |
INSUFFICIENT_CREDITS | Your team does not have enough credits to send this message or fax. Add credits, then retry. See Credits. |
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, their activation code read or their tier and data changed for this account right now. The message gives the reason. 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. |