# Error codes

> Complete catalog of all API error codes with recovery instructions

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)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="api_key_invalid"><td style={{ whiteSpace: 'nowrap' }}>`API_KEY_INVALID`</td><td>The API key provided is invalid or does not exist. Check your API key in [Settings > API](https://web.withallo.com/settings/api).</td></tr>
    <tr id="api_key_revoked"><td style={{ whiteSpace: 'nowrap' }}>`API_KEY_REVOKED`</td><td>This API key has been revoked. Create a new API key in [Settings > API](https://web.withallo.com/settings/api).</td></tr>
    <tr id="unauthorized"><td style={{ whiteSpace: 'nowrap' }}>`UNAUTHORIZED`</td><td>Authentication is required. Provide a valid API key in the `Authorization` header as `Api-Key <your-key>`.</td></tr>
  </tbody>
</table>

## Permission errors (403)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="api_key_insufficient_scope"><td style={{ whiteSpace: 'nowrap' }}>`API_KEY_INSUFFICIENT_SCOPE`</td><td>This API key lacks the required scope. Create a new key with the required scope. See [scope-to-endpoint mapping](/docs/guides/authentication#scope-to-endpoint-mapping).</td></tr>
    <tr id="api_key_trial_not_allowed"><td style={{ whiteSpace: 'nowrap' }}>`API_KEY_TRIAL_NOT_ALLOWED`</td><td>API access is not available on trial plans. Upgrade to a paid plan.</td></tr>
    <tr id="forbidden"><td style={{ whiteSpace: 'nowrap' }}>`FORBIDDEN`</td><td>You do not have permission to perform this action. Contact your workspace admin.</td></tr>
    <tr id="a2p_not_enabled"><td style={{ whiteSpace: 'nowrap' }}>`A2P_NOT_ENABLED`</td><td>A2P (Application-to-Person) SMS is not enabled for this number. Complete 10DLC registration in the Allo dashboard.</td></tr>
    <tr id="fax_not_available"><td style={{ whiteSpace: 'nowrap' }}>`FAX_NOT_AVAILABLE`</td><td>Faxing is not available for this account. Contact Allo support to get it enabled.</td></tr>
    <tr id="allo_number_forbidden"><td style={{ whiteSpace: 'nowrap' }}>`ALLO_NUMBER_FORBIDDEN`</td><td>You do not have access to this Allo line. List the lines you can access with `GET /v2/api/numbers`.</td></tr>
    <tr id="not_note_author"><td style={{ whiteSpace: 'nowrap' }}>`NOT_NOTE_AUTHOR`</td><td>Only the note's author can edit or delete it.</td></tr>
    <tr id="not_comment_author"><td style={{ whiteSpace: 'nowrap' }}>`NOT_COMMENT_AUTHOR`</td><td>Only the comment's author can edit it.</td></tr>
    <tr id="agent_transfer_rule_member_no_line_access"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_TRANSFER_RULE_MEMBER_NO_LINE_ACCESS`</td><td>The teammate a transfer rule points at has no access to this line. Pick one who does, from `GET /v2/api/users`.</td></tr>
    <tr id="partner_access_required"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCESS_REQUIRED`</td><td>This account is not an enabled partner. Partner access is granted by Allo, write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
    <tr id="partner_contract_cannot_provision"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_CONTRACT_CANNOT_PROVISION`</td><td>Your partner contract does not allow creating or pricing accounts. Only Discounted licence (reseller) partners can.</td></tr>
    <tr id="partner_cannot_deactivate"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_CANNOT_DEACTIVATE`</td><td>Your partner contract does not allow deactivating this account. Only Discounted licence (reseller) partners can.</td></tr>
    <tr id="account_suspended"><td style={{ whiteSpace: 'nowrap' }}>`ACCOUNT_SUSPENDED`</td><td>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`.</td></tr>
    <tr id="recording_access_denied"><td style={{ whiteSpace: 'nowrap' }}>`RECORDING_ACCESS_DENIED`</td><td>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.</td></tr>
    <tr id="recording_download_restricted"><td style={{ whiteSpace: 'nowrap' }}>`RECORDING_DOWNLOAD_RESTRICTED`</td><td>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.</td></tr>
    <tr id="view_permission_denied"><td style={{ whiteSpace: 'nowrap' }}>`VIEW_PERMISSION_DENIED`</td><td>Only the owner of a team view or a team ADMIN or MANAGER can update or delete it.</td></tr>
  </tbody>
</table>

## Validation errors (400)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="invalid_request_body"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_REQUEST_BODY`</td><td>The request body could not be parsed. Ensure Content-Type is `application/json` and the body is well-formed JSON.</td></tr>
    <tr id="missing_parameter"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_PARAMETER`</td><td>A required query parameter is missing. Add the parameter named in the `param` field.</td></tr>
    <tr id="invalid_parameter"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_PARAMETER`</td><td>A query parameter is malformed, for example `pinned=yes` instead of `true` or `false`. The parameter is named in `param`.</td></tr>
    <tr id="missing_header"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_HEADER`</td><td>A required header is missing. Add the header named in the `param` field.</td></tr>
    <tr id="unsupported_media_type"><td style={{ whiteSpace: 'nowrap' }}>`UNSUPPORTED_MEDIA_TYPE`</td><td>The Content-Type is not supported. Use `application/json`. Returns `415`.</td></tr>
    <tr id="invalid_page_size"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_PAGE_SIZE`</td><td>The `size` parameter value is invalid. Provide a numeric value between 1 and 100.</td></tr>
    <tr id="invalid_search_query"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_SEARCH_QUERY`</td><td>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.</td></tr>
    <tr id="missing_allo_number"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_ALLO_NUMBER`</td><td>The `allo_number` parameter is required. Add it to your request. List your numbers with `GET /v2/api/numbers`.</td></tr>
    <tr id="invalid_date_range"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_DATE_RANGE`</td><td>The date range is invalid: `from` must be before `to`. Use `YYYY-MM-DD` format.</td></tr>
    <tr id="date_range_too_wide"><td style={{ whiteSpace: 'nowrap' }}>`DATE_RANGE_TOO_WIDE`</td><td>The date range exceeds the maximum allowed number of days. Narrow your date range.</td></tr>
    <tr id="invalid_item_id"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_ITEM_ID`</td><td>Item ID has an unrecognized prefix. Use IDs from the conversations API: `cll-` for calls, `msg-` for messages.</td></tr>
    <tr id="batch_too_large"><td style={{ whiteSpace: 'nowrap' }}>`BATCH_TOO_LARGE`</td><td>Batch size exceeds the maximum of 100. Split your request into batches of 100 or fewer.</td></tr>
    <tr id="tags_required"><td style={{ whiteSpace: 'nowrap' }}>`TAGS_REQUIRED`</td><td>At least one tag is required. Provide a non-empty `tags` array. List available tags with `GET /v2/api/tags`.</td></tr>
    <tr id="invalid_action"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_ACTION`</td><td>Unknown action value. Use one of: `READ`, `UNREAD`, `ARCHIVE`, `UNARCHIVE`.</td></tr>
    <tr id="invalid_granularity"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_GRANULARITY`</td><td>Unknown granularity value. Use one of: `DAY`, `WEEK`, `MONTH`.</td></tr>
    <tr id="invalid_group_by"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_GROUP_BY`</td><td>Unknown `group_by` value. Check the `suggestion` field for allowed values.</td></tr>
    <tr id="unsupported_extend_value"><td style={{ whiteSpace: 'nowrap' }}>`UNSUPPORTED_EXTEND_VALUE`</td><td>Unknown `extend` value. Currently supported: `transcript`.</td></tr>
    <tr id="method_not_allowed"><td style={{ whiteSpace: 'nowrap' }}>`METHOD_NOT_ALLOWED`</td><td>HTTP method not supported for this endpoint. Check the `suggestion` field for supported methods. Returns `405`.</td></tr>
    <tr id="invalid_phone_format"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_PHONE_FORMAT`</td><td>Phone number is not valid E.164 format. Use format: `+14155551234` (+ prefix, country code, no spaces or dashes).</td></tr>
    <tr id="invalid_to_number"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_TO_NUMBER`</td><td>The destination number is invalid or cannot be reached. Provide a valid E.164 phone number.</td></tr>
    <tr id="to_number_country_mismatch"><td style={{ whiteSpace: 'nowrap' }}>`TO_NUMBER_COUNTRY_MISMATCH`</td><td>Cross-country SMS is not supported for this number. Use a phone number in the same country as the recipient.</td></tr>
    <tr id="number_not_sms_enabled"><td style={{ whiteSpace: 'nowrap' }}>`NUMBER_NOT_SMS_ENABLED`</td><td>This number does not have outbound SMS enabled. Enable SMS in the dashboard, or use a different number from `GET /v2/api/numbers`.</td></tr>
    <tr id="sender_id_inbox_cannot_send_sms"><td style={{ whiteSpace: 'nowrap' }}>`SENDER_ID_INBOX_CANNOT_SEND_SMS`</td><td>Sender ID inboxes cannot send SMS messages. Use a regular phone number instead.</td></tr>
    <tr id="sender_id_not_active"><td style={{ whiteSpace: 'nowrap' }}>`SENDER_ID_NOT_ACTIVE`</td><td>The sender ID is not active. Activate the sender ID in the Allo dashboard before sending.</td></tr>
    <tr id="message_not_compliant"><td style={{ whiteSpace: 'nowrap' }}>`MESSAGE_NOT_COMPLIANT`</td><td>Message content does not comply with messaging compliance rules. Remove disallowed content and retry.</td></tr>
    <tr id="landline_number_not_supported"><td style={{ whiteSpace: 'nowrap' }}>`LANDLINE_NUMBER_NOT_SUPPORTED`</td><td>The destination number is a landline and cannot receive SMS. Provide a mobile phone number instead.</td></tr>
    <tr id="fax_not_supported_on_number"><td style={{ whiteSpace: 'nowrap' }}>`FAX_NOT_SUPPORTED_ON_NUMBER`</td><td>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`.</td></tr>
    <tr id="fax_not_enabled_on_line"><td style={{ whiteSpace: 'nowrap' }}>`FAX_NOT_ENABLED_ON_LINE`</td><td>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.</td></tr>
    <tr id="fax_file_not_pdf"><td style={{ whiteSpace: 'nowrap' }}>`FAX_FILE_NOT_PDF`</td><td>The fax file is not a PDF. Send the document as a PDF with content type `application/pdf`.</td></tr>
    <tr id="fax_file_empty"><td style={{ whiteSpace: 'nowrap' }}>`FAX_FILE_EMPTY`</td><td>The fax file is empty. Attach a non-empty PDF in the `file` part.</td></tr>
    <tr id="max_upload_size_exceeded"><td style={{ whiteSpace: 'nowrap' }}>`MAX_UPLOAD_SIZE_EXCEEDED`</td><td>The uploaded file is too large. A fax file can be at most 12 MB: compress the PDF or split it into several faxes.</td></tr>
    <tr id="summary_template_key_required"><td style={{ whiteSpace: 'nowrap' }}>`SUMMARY_TEMPLATE_KEY_REQUIRED`</td><td>The call has more than one completed summary template. Set `template_key` to disambiguate (e.g. `MARKDOWN_CLASSIC` or `MARKDOWN_SHORT_CALL`).</td></tr>
    <tr id="empty_note_content"><td style={{ whiteSpace: 'nowrap' }}>`EMPTY_NOTE_CONTENT`</td><td>The note or comment content is empty. Provide a non-blank `content` value.</td></tr>
    <tr id="note_content_too_long"><td style={{ whiteSpace: 'nowrap' }}>`NOTE_CONTENT_TOO_LONG`</td><td>The note or comment content exceeds the maximum of 4,000 characters. Shorten the content.</td></tr>
    <tr id="missing_allo_number_or_sender_id"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_ALLO_NUMBER_OR_SENDER_ID`</td><td>Provide either `allo_number` (E.164 Allo line) or `sender_id` (sender-ID inbox). List your numbers with `GET /v2/api/numbers`.</td></tr>
    <tr id="contact_notes_unavailable"><td style={{ whiteSpace: 'nowrap' }}>`CONTACT_NOTES_UNAVAILABLE`</td><td>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.</td></tr>
    <tr id="invalid_thread_entity_type"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_THREAD_ENTITY_TYPE`</td><td>Unknown `entity_type` value. Use one of: `CALL`, `TEXT_MESSAGE`, `CONVERSATION_NOTE`.</td></tr>
    <tr id="unknown_field"><td style={{ whiteSpace: 'nowrap' }}>`UNKNOWN_FIELD`</td><td>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`.</td></tr>
    <tr id="missing_field"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_FIELD`</td><td>A required field is missing, named in `param`. Inside a collection it carries the index, for example `transfer_rules[1].description`.</td></tr>
    <tr id="invalid_phone_number"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_PHONE_NUMBER`</td><td>The phone number named in `param` could not be read. Use E.164 format, for example `+14155551234`.</td></tr>
    <tr id="invalid_timezone"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_TIMEZONE`</td><td>Not an IANA timezone identifier. Use one such as `Europe/Paris` or `America/New_York`.</td></tr>
    <tr id="invalid_agent_language"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_AGENT_LANGUAGE`</td><td>Unknown AI receptionist language. The accepted values are listed in the message.</td></tr>
    <tr id="invalid_agent_capability"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_AGENT_CAPABILITY`</td><td>Unknown capability key. Use `SCHEDULING`, `CALL_TRANSFER` or `WARM_TRANSFER`, in upper case.</td></tr>
    <tr id="agent_transfer_rule_target_required"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_TRANSFER_RULE_TARGET_REQUIRED`</td><td>A transfer rule is missing the target its type requires: `target_number`, `target_member_id` or `target_line_number`.</td></tr>
    <tr id="agent_no_forwarding_number"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_NO_FORWARDING_NUMBER`</td><td>Turning the AI receptionist off forwards calls to your business phone, and none is set on the workspace.</td></tr>
    <tr id="agent_calendar_team_mismatch"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_CALENDAR_TEAM_MISMATCH`</td><td>The calendar belongs to another team. List the ones you can use with `GET /v2/api/calendars`.</td></tr>
    <tr id="agent_calendar_event_types_not_supported"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_CALENDAR_EVENT_TYPES_NOT_SUPPORTED`</td><td>This calendar's provider has no event types. Map it to an empty list.</td></tr>
    <tr id="invalid_knowledge_url"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_KNOWLEDGE_URL`</td><td>The URL has no public host. Send the URL of a publicly reachable site, for example `https://example.com`.</td></tr>
    <tr id="prompt_sections_required"><td style={{ whiteSpace: 'nowrap' }}>`PROMPT_SECTIONS_REQUIRED`</td><td>`sections` was empty. It replaces the whole prompt, so it must carry every section to keep.</td></tr>
    <tr id="invalid_agent_prompt_section"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_AGENT_PROMPT_SECTION`</td><td>Unknown prompt section key. The accepted keys are listed in the message.</td></tr>
    <tr id="duplicate_agent_prompt_section"><td style={{ whiteSpace: 'nowrap' }}>`DUPLICATE_AGENT_PROMPT_SECTION`</td><td>A prompt section appears more than once. Send each at most once.</td></tr>
    <tr id="invalid_agent_prompt_section_body"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_AGENT_PROMPT_SECTION_BODY`</td><td>A prompt section carries the wrong body. `required_fields` takes `fields`, every other section takes `content`.</td></tr>
    <tr id="missing_agent_prompt_section"><td style={{ whiteSpace: 'nowrap' }}>`MISSING_AGENT_PROMPT_SECTION`</td><td>`objective`, `personality` and `behaviors` are required and one is missing or blank.</td></tr>
    <tr id="agent_prompt_section_too_long"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_PROMPT_SECTION_TOO_LONG`</td><td>A prompt section exceeds 3,000 characters. Shorten it.</td></tr>
    <tr id="agent_prompt_too_long"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_PROMPT_TOO_LONG`</td><td>The prompt rendered from all sections exceeds 25,000 characters. Shorten the sections.</td></tr>
    <tr id="attribute_label_invalid"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_LABEL_INVALID`</td><td>`label` is blank, longer than 255 characters, or has no letter or digit.</td></tr>
    <tr id="attribute_key_reserved"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_KEY_RESERVED`</td><td>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.</td></tr>
    <tr id="attribute_options_not_supported"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_OPTIONS_NOT_SUPPORTED`</td><td>`options` was sent for an attribute that is not a dropdown. Send `options` only for `DROPDOWN` attributes.</td></tr>
    <tr id="attribute_option_invalid"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_OPTION_INVALID`</td><td>Every option needs a non-blank `label` of at most 255 characters, unique within the attribute, and a dropdown needs at least one option.</td></tr>
    <tr id="attribute_built_in"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_BUILT_IN`</td><td>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.</td></tr>
    <tr id="custom_attribute_key_unknown"><td style={{ whiteSpace: 'nowrap' }}>`CUSTOM_ATTRIBUTE_KEY_UNKNOWN`</td><td>`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>`.</td></tr>
    <tr id="custom_attribute_value_invalid"><td style={{ whiteSpace: 'nowrap' }}>`CUSTOM_ATTRIBUTE_VALUE_INVALID`</td><td>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>`.</td></tr>
    <tr id="esim_not_available_in_country"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_NOT_AVAILABLE_IN_COUNTRY`</td><td>`number_preference.esim` is `true` with a country other than `FR`. eSIM numbers are only available in France.</td></tr>
    <tr id="invalid_esim_tier"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_ESIM_TIER`</td><td>Unknown eSIM tier. Use a `code` from `GET /v2/api/partner/accounts/{account_id}/esims/offer`.</td></tr>
    <tr id="invalid_esim_topup"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_ESIM_TOPUP`</td><td>Unknown eSIM top-up, named in `param` (`code`). Use a `top_ups[].code` from `GET /v2/api/partner/accounts/{account_id}/esims/offer`.</td></tr>
    <tr id="partner_account_owner_not_removable"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_OWNER_NOT_REMOVABLE`</td><td>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}`.</td></tr>
    <tr id="partner_member_number_choice_conflict"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_MEMBER_NUMBER_CHOICE_CONFLICT`</td><td>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.</td></tr>
    <tr id="esim_identity_incomplete"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_IDENTITY_INCOMPLETE`</td><td>The eSIM `identity` is missing or incomplete: `corporate_name`, `postal_address`, `postal_code` (5 digits) and `city` are required.</td></tr>
    <tr id="sender_id_invalid_format"><td style={{ whiteSpace: 'nowrap' }}>`SENDER_ID_INVALID_FORMAT`</td><td>The `sender_id` must be 1 to 11 letters or digits, with no spaces or symbols, for example `MYBRAND`.</td></tr>
    <tr id="example_content_too_long"><td style={{ whiteSpace: 'nowrap' }}>`EXAMPLE_CONTENT_TOO_LONG`</td><td>The `example_content` of the sender ID is longer than 1,000 characters. Shorten it.</td></tr>
    <tr id="invalid_idempotency_key"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_IDEMPOTENCY_KEY`</td><td>The `Idempotency-Key` header must be 8 to 100 letters, digits, `-` or `_`. Send a UUID.</td></tr>
    <tr id="idempotency_key_required"><td style={{ whiteSpace: 'nowrap' }}>`IDEMPOTENCY_KEY_REQUIRED`</td><td>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.</td></tr>
    <tr id="invalid_number_preference"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_NUMBER_PREFERENCE`</td><td>The `country` of the number preference is unknown or not supported. Send an ISO country code such as `FR`.</td></tr>
    <tr id="invalid_member_role"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_MEMBER_ROLE`</td><td>Unknown member `role`. Use `ADMIN`, `MANAGER` or `MEMBER`.</td></tr>
    <tr id="invalid_filter_field"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_FILTER_FIELD`</td><td>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`.</td></tr>
    <tr id="invalid_filter_operator"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_FILTER_OPERATOR`</td><td>A view filter `operator` does not match the type of its field.</td></tr>
    <tr id="invalid_filter_value"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_FILTER_VALUE`</td><td>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.</td></tr>
    <tr id="invalid_sort_field"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_SORT_FIELD`</td><td>A view sort `field` is neither a built-in field nor a custom field `key` from `GET /v2/api/crm/attributes`.</td></tr>
    <tr id="field_not_sortable"><td style={{ whiteSpace: 'nowrap' }}>`FIELD_NOT_SORTABLE`</td><td>A view sort `field` exists but cannot be sorted on. Use a built-in sortable field or a sortable custom field.</td></tr>
    <tr id="invalid_request"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_REQUEST`</td><td>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.</td></tr>
    <tr id="inbox_name_required"><td style={{ whiteSpace: 'nowrap' }}>`INBOX_NAME_REQUIRED`</td><td>An inbox needs a non-blank `name`. Send a short name such as `Sales`.</td></tr>
    <tr id="invalid_inbox_source"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_INBOX_SOURCE`</td><td>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`.</td></tr>
    <tr id="invalid_inbox_filters"><td style={{ whiteSpace: 'nowrap' }}>`INVALID_INBOX_FILTERS`</td><td>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`.</td></tr>
    <tr id="inbox_limit_reached"><td style={{ whiteSpace: 'nowrap' }}>`INBOX_LIMIT_REACHED`</td><td>The inbox owner already has 50 inboxes. Delete one with `DELETE /v2/api/inboxes/{inbox_id}`.</td></tr>
    <tr id="feature_not_supported"><td style={{ whiteSpace: 'nowrap' }}>`FEATURE_NOT_SUPPORTED`</td><td>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.</td></tr>
    <tr id="contact_filter_not_supported"><td style={{ whiteSpace: 'nowrap' }}>`CONTACT_FILTER_NOT_SUPPORTED`</td><td>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}`.</td></tr>
  </tbody>
</table>

## Not found errors (404)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="conversation_item_not_found"><td style={{ whiteSpace: 'nowrap' }}>`CONVERSATION_ITEM_NOT_FOUND`</td><td>No call or message found with this ID. Search for the item with `POST /v2/api/conversations/items/search`.</td></tr>
    <tr id="member_not_found"><td style={{ whiteSpace: 'nowrap' }}>`MEMBER_NOT_FOUND`</td><td>No team member found with this ID. List team members with `GET /v2/api/users`.</td></tr>
    <tr id="team_not_found"><td style={{ whiteSpace: 'nowrap' }}>`TEAM_NOT_FOUND`</td><td>No team found for the authenticated user. Check team setup in the Allo dashboard.</td></tr>
    <tr id="user_not_found"><td style={{ whiteSpace: 'nowrap' }}>`USER_NOT_FOUND`</td><td>The authenticated user account was not found. Verify the API key is associated with an active account.</td></tr>
    <tr id="business_not_found"><td style={{ whiteSpace: 'nowrap' }}>`BUSINESS_NOT_FOUND`</td><td>No business account found for the authenticated user. Ensure the account has completed onboarding.</td></tr>
    <tr id="call_not_found"><td style={{ whiteSpace: 'nowrap' }}>`CALL_NOT_FOUND`</td><td>No call found with this ID. Search calls with `POST /v2/api/conversations/items/search`.</td></tr>
    <tr id="text_message_not_found"><td style={{ whiteSpace: 'nowrap' }}>`TEXT_MESSAGE_NOT_FOUND`</td><td>No text message found with this ID. Search messages with `POST /v2/api/conversations/items/search`.</td></tr>
    <tr id="phone_number_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PHONE_NUMBER_NOT_FOUND`</td><td>No phone number found for your account. List your numbers with `GET /v2/api/numbers`.</td></tr>
    <tr id="from_number_not_found"><td style={{ whiteSpace: 'nowrap' }}>`FROM_NUMBER_NOT_FOUND`</td><td>No Allo phone number found for your account. List your available numbers with `GET /v2/api/numbers`.</td></tr>
    <tr id="tag_not_found"><td style={{ whiteSpace: 'nowrap' }}>`TAG_NOT_FOUND`</td><td>The tag does not exist on this conversation item. It may have already been removed.</td></tr>
    <tr id="sender_id_not_found"><td style={{ whiteSpace: 'nowrap' }}>`SENDER_ID_NOT_FOUND`</td><td>No active sender ID found. Check your sender IDs in the Allo dashboard.</td></tr>
    <tr id="summary_template_not_found"><td style={{ whiteSpace: 'nowrap' }}>`SUMMARY_TEMPLATE_NOT_FOUND`</td><td>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.</td></tr>
    <tr id="endpoint_not_found"><td style={{ whiteSpace: 'nowrap' }}>`ENDPOINT_NOT_FOUND`</td><td>No endpoint found at this URL. Check the URL and HTTP method. See the [API reference](/docs).</td></tr>
    <tr id="person_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PERSON_NOT_FOUND`</td><td>No person found with this ID (`per-*`). Search people with `POST /v2/api/crm/people/search`.</td></tr>
    <tr id="note_not_found"><td style={{ whiteSpace: 'nowrap' }}>`NOTE_NOT_FOUND`</td><td>No note found with this ID. List a conversation's notes with `GET /v2/api/conversations/{contact_number}/notes`.</td></tr>
    <tr id="thread_not_found"><td style={{ whiteSpace: 'nowrap' }}>`THREAD_NOT_FOUND`</td><td>No thread found with this ID. Find an item's thread with `GET /v2/api/threads?entity_type=...&entity_id=...`.</td></tr>
    <tr id="thread_comment_not_found"><td style={{ whiteSpace: 'nowrap' }}>`THREAD_COMMENT_NOT_FOUND`</td><td>No thread comment found with this ID. Fetch the thread with `GET /v2/api/threads/{id}` to see its comments.</td></tr>
    <tr id="agent_voice_not_found"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_VOICE_NOT_FOUND`</td><td>No voice with this `voice_id`. List the catalog with `GET /v2/api/voices`.</td></tr>
    <tr id="agent_knowledge_not_found"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_KNOWLEDGE_NOT_FOUND`</td><td>No knowledge entry of this kind with this ID for the line. List them with `GET /v2/api/numbers/{number}/agent`.</td></tr>
    <tr id="agent_calendar_not_found"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_CALENDAR_NOT_FOUND`</td><td>No calendar with this ID is visible to you. List them with `GET /v2/api/calendars`.</td></tr>
    <tr id="partner_esim_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_NOT_FOUND`</td><td>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`.</td></tr>
    <tr id="partner_esim_number_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_NUMBER_NOT_FOUND`</td><td>The phone number does not belong to this account. Use one of the account's `phone_numbers` from `GET /v2/api/partner/accounts/{id}`.</td></tr>
    <tr id="partner_esim_holder_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_HOLDER_NOT_FOUND`</td><td>The `holder_id` user cannot hold an eSIM for this number. Leave `holder_id` out to make the account the holder.</td></tr>
    <tr id="partner_sender_id_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_SENDER_ID_NOT_FOUND`</td><td>No sender ID with this ID is declared on this account. List them with `GET /v2/api/partner/accounts/{account_id}/sender_ids`.</td></tr>
    <tr id="partner_account_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_NOT_FOUND`</td><td>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.</td></tr>
    <tr id="partner_account_member_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_MEMBER_NOT_FOUND`</td><td>No member with this ID is in the account's workspace. List the account's members with `GET /v2/api/partner/accounts/{id}/members`.</td></tr>
    <tr id="partner_account_number_not_found"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_NUMBER_NOT_FOUND`</td><td>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.</td></tr>
    <tr id="recording_not_found"><td style={{ whiteSpace: 'nowrap' }}>`RECORDING_NOT_FOUND`</td><td>The call has no recording, or the ID is an SMS (`msg-*`). Only answered calls on lines with call recording on have one.</td></tr>
    <tr id="attribute_not_found"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_NOT_FOUND`</td><td>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.</td></tr>
    <tr id="user_has_no_team"><td style={{ whiteSpace: 'nowrap' }}>`USER_HAS_NO_TEAM`</td><td>`owner_type` is `TEAM` but the user does not belong to a team. Use `USER`.</td></tr>
    <tr id="view_not_found"><td style={{ whiteSpace: 'nowrap' }}>`VIEW_NOT_FOUND`</td><td>No view with this ID, or you cannot see it. List views with `GET /v2/api/crm/views`.</td></tr>
    <tr id="inbox_not_found"><td style={{ whiteSpace: 'nowrap' }}>`INBOX_NOT_FOUND`</td><td>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.</td></tr>
  </tbody>
</table>

## Conflict errors (409)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="tag_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`TAG_ALREADY_EXISTS`</td><td>This tag is already applied to the conversation item. No action needed.</td></tr>
    <tr id="other_transaction_in_progress"><td style={{ whiteSpace: 'nowrap' }}>`OTHER_TRANSACTION_IN_PROGRESS`</td><td>Another operation on this resource is in progress. Wait a moment and retry.</td></tr>
    <tr id="number_already_assigned"><td style={{ whiteSpace: 'nowrap' }}>`NUMBER_ALREADY_ASSIGNED`</td><td>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}`.</td></tr>
    <tr id="idempotency_key_reuse"><td style={{ whiteSpace: 'nowrap' }}>`IDEMPOTENCY_KEY_REUSE`</td><td>This idempotency key was already used for a different endpoint or HTTP method. Use a unique key per distinct request. See [Idempotency](/docs/guides/error-handling#idempotency).</td></tr>
    <tr id="thread_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`THREAD_ALREADY_EXISTS`</td><td>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`.</td></tr>
    <tr id="agent_knowledge_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_KNOWLEDGE_ALREADY_EXISTS`</td><td>The line already uses a website with this URL. Reuse the existing entry.</td></tr>
    <tr id="agent_line_not_assigned"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_LINE_NOT_ASSIGNED`</td><td>The line has no phone number assigned, so its AI receptionist can neither answer nor forward.</td></tr>
    <tr id="attribute_key_conflict"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_KEY_CONFLICT`</td><td>A custom field or attribute with this key already exists with another type. Choose another label, or reuse the existing one.</td></tr>
    <tr id="attribute_slots_exhausted"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_SLOTS_EXHAUSTED`</td><td>No free slot is left for custom fields or attributes of this type. Reuse an existing one or create one with another type.</td></tr>
    <tr id="attribute_managed_by_integration"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_MANAGED_BY_INTEGRATION`</td><td>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.</td></tr>
    <tr id="attribute_concurrent_modification"><td style={{ whiteSpace: 'nowrap' }}>`ATTRIBUTE_CONCURRENT_MODIFICATION`</td><td>Attributes were modified at the same time. Retry the request.</td></tr>
    <tr id="esim_not_eligible"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_NOT_ELIGIBLE`</td><td>The number cannot carry an eSIM. Create the account with `number_preference.esim` set to `true` to get an eSIM number.</td></tr>
    <tr id="esim_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_ALREADY_EXISTS`</td><td>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.</td></tr>
    <tr id="partner_esim_not_revocable"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_NOT_REVOCABLE`</td><td>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}`.</td></tr>
    <tr id="partner_esim_move_in_progress"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_MOVE_IN_PROGRESS`</td><td>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.</td></tr>
    <tr id="partner_esim_move_failed"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_MOVE_FAILED`</td><td>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.</td></tr>
    <tr id="partner_esim_revoked"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ESIM_REVOKED`</td><td>The eSIM was revoked, so its activation code is no longer available. To give the number a new eSIM, order one.</td></tr>
    <tr id="partner_number_has_live_esim"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_NUMBER_HAS_LIVE_ESIM`</td><td>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.</td></tr>
    <tr id="esim_order_in_progress"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_ORDER_IN_PROGRESS`</td><td>An eSIM order for this number is still provisioning. Always `retryable: true`. Wait for the `partner.esim.ready` or `partner.esim.failed` webhook.</td></tr>
    <tr id="esim_order_needs_support"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_ORDER_NEEDS_SUPPORT`</td><td>A previous eSIM order for this number was charged but did not complete, and Allo support is handling it. Write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) before ordering again.</td></tr>
    <tr id="esim_not_ready"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_NOT_READY`</td><td>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.</td></tr>
    <tr id="esim_not_active"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_NOT_ACTIVE`</td><td>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`.</td></tr>
    <tr id="esim_tier_change_conflict"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_TIER_CHANGE_CONFLICT`</td><td>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.</td></tr>
    <tr id="esim_topup_pending"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_TOPUP_PENDING`</td><td>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.</td></tr>
    <tr id="esim_subscription_conflict"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_SUBSCRIPTION_CONFLICT`</td><td>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 [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
    <tr id="sender_id_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`SENDER_ID_ALREADY_EXISTS`</td><td>The sender ID already belongs to another Allo account. A sender ID belongs to one account only: choose another name.</td></tr>
    <tr id="max_sender_ids_reached"><td style={{ whiteSpace: 'nowrap' }}>`MAX_SENDER_IDS_REACHED`</td><td>The account already has 3 sender IDs, the maximum. List them with `GET /v2/api/partner/accounts/{account_id}/sender_ids`.</td></tr>
    <tr id="partner_account_already_exists"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_ALREADY_EXISTS`</td><td>The email or personal mobile, named in `param`, already belongs to an Allo account. Use another one.</td></tr>
    <tr id="no_number_available"><td style={{ whiteSpace: 'nowrap' }}>`NO_NUMBER_AVAILABLE`</td><td>No number matches the country and prefix you asked for. Nothing is charged. Retry later, or ask for another country or prefix.</td></tr>
    <tr id="regulatory_verification_required"><td style={{ whiteSpace: 'nowrap' }}>`REGULATORY_VERIFICATION_REQUIRED`</td><td>A number in this country needs the account's regulatory verification first. Nothing is charged. Choose another country, or write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
    <tr id="partner_account_busy"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_BUSY`</td><td>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.</td></tr>
    <tr id="idempotency_key_already_used"><td style={{ whiteSpace: 'nowrap' }}>`IDEMPOTENCY_KEY_ALREADY_USED`</td><td>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.</td></tr>
    <tr id="partner_account_deactivating"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_DEACTIVATING`</td><td>The account is being deactivated at the end of its billing period, so it takes no more numbers or members.</td></tr>
    <tr id="partner_account_subscription_conflict"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT`</td><td>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 [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
    <tr id="pin_limit_reached"><td style={{ whiteSpace: 'nowrap' }}>`PIN_LIMIT_REACHED`</td><td>The user already has 10 pinned conversations. Unpin one with `DELETE /v2/api/conversations/{contact_number}/pin` first.</td></tr>
  </tbody>
</table>

## Unprocessable errors (422)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="contact_filter_too_large"><td style={{ whiteSpace: 'nowrap' }}>`CONTACT_FILTER_TOO_LARGE`</td><td>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.</td></tr>
  </tbody>
</table>

## Payment errors (402)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="esim_payment_failed"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_PAYMENT_FAILED`</td><td>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`.</td></tr>
    <tr id="partner_credit_insufficient"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_CREDIT_INSUFFICIENT`</td><td>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.</td></tr>
    <tr id="insufficient_credits"><td style={{ whiteSpace: 'nowrap' }}>`INSUFFICIENT_CREDITS`</td><td>Your team does not have enough credits to send this message or fax. Add credits, then retry. See [Credits](/help/billing/credits).</td></tr>
    <tr id="partner_billing_failed"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_BILLING_FAILED`</td><td>Allo could not charge your card, for example because it was declined. Nothing is created. Update your card, then retry.</td></tr>
    <tr id="partner_subscription_not_billable"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_SUBSCRIPTION_NOT_BILLABLE`</td><td>There is no subscription or billing account Allo can charge for this request. Write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
  </tbody>
</table>

## Rate limit errors (429)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="rate_limit_exceeded"><td style={{ whiteSpace: 'nowrap' }}>`RATE_LIMIT_EXCEEDED`</td><td>Per-second rate limit exceeded. Always `retryable: true`. Wait `retry_after_seconds` before retrying.</td></tr>
    <tr id="trial_sms_limit_reached"><td style={{ whiteSpace: 'nowrap' }}>`TRIAL_SMS_LIMIT_REACHED`</td><td>Trial account daily SMS limit reached. Upgrade your plan to send more messages.</td></tr>
    <tr id="sms_limit_reached"><td style={{ whiteSpace: 'nowrap' }}>`SMS_LIMIT_REACHED`</td><td>Daily API SMS limit reached. Wait until tomorrow or contact support to increase your limit.</td></tr>
    <tr id="daily_sms_limit_reached"><td style={{ whiteSpace: 'nowrap' }}>`DAILY_SMS_LIMIT_REACHED`</td><td>Daily SMS limit reached for this number. Wait until tomorrow to send more messages from this number.</td></tr>
  </tbody>
</table>

## Server errors (500)

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr id="internal_server_error"><td style={{ whiteSpace: 'nowrap' }}>`INTERNAL_SERVER_ERROR`</td><td>An unexpected error occurred. Retry the request. If it persists, contact support@withallo.com with your `request_id`.</td></tr>
    <tr id="agent_calendar_event_types_fetch_failed"><td style={{ whiteSpace: 'nowrap' }}>`AGENT_CALENDAR_EVENT_TYPES_FETCH_FAILED`</td><td>The calendar provider could not be reached. Always `retryable: true`. If it persists, renew the calendar connection in the Allo app.</td></tr>
    <tr id="esim_unavailable"><td style={{ whiteSpace: 'nowrap' }}>`ESIM_UNAVAILABLE`</td><td>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 [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) if it persists.</td></tr>
    <tr id="partner_billing_unavailable"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_BILLING_UNAVAILABLE`</td><td>Billing is temporarily unavailable. Retry, with the same `Idempotency-Key` if you sent one: it resumes the same charge.</td></tr>
    <tr id="partner_number_setup_failed"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_NUMBER_SETUP_FAILED`</td><td>The number could not be set up, and the charge was taken back. Not retryable: write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co).</td></tr>
    <tr id="partner_number_kept"><td style={{ whiteSpace: 'nowrap' }}>`PARTNER_NUMBER_KEPT`</td><td>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 [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) with the number.</td></tr>
    <tr id="recording_download_unavailable"><td style={{ whiteSpace: 'nowrap' }}>`RECORDING_DOWNLOAD_UNAVAILABLE`</td><td>The recording download link could not be created. Always `retryable: true`: retry in a few seconds.</td></tr>
  </tbody>
</table>
