> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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><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><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><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><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](/en/v2/api-reference/guides/authentication#scope-to-endpoint-mapping).</td></tr>
    <tr><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><td style={{ whiteSpace: 'nowrap' }}>`FORBIDDEN`</td><td>You do not have permission to perform this action. Contact your workspace admin.</td></tr>
    <tr><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>
  </tbody>
</table>

## Validation errors — 400

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><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><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><td style={{ whiteSpace: 'nowrap' }}>`MISSING_HEADER`</td><td>A required header is missing. Add the header named in the `param` field.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}>`UNSUPPORTED_MEDIA_TYPE`</td><td>The Content-Type is not supported. Use `application/json`. Returns `415`.</td></tr>
    <tr><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><td style={{ whiteSpace: 'nowrap' }}>`INVALID_SEARCH_QUERY`</td><td>The `search` parameter must contain at least one alphanumeric character. Special characters are stripped automatically — provide plain-text keywords (e.g., `"john"` or `"missed call"`). Words are combined with AND and prefix-matched.</td></tr>
    <tr><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><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><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><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><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><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><td style={{ whiteSpace: 'nowrap' }}>`INVALID_ACTION`</td><td>Unknown action value. Use one of: `READ`, `UNREAD`, `ARCHIVE`, `UNARCHIVE`.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}>`INVALID_GRANULARITY`</td><td>Unknown granularity value. Use one of: `DAY`, `WEEK`, `MONTH`.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}>`INVALID_GROUP_BY`</td><td>Unknown `group_by` value. Check the `suggestion` field for allowed values.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}>`UNSUPPORTED_EXTEND_VALUE`</td><td>Unknown `extend` value. Currently supported: `transcript`.</td></tr>
    <tr><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><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><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><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><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><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><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><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><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><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>
  </tbody>
</table>

## Not found errors — 404

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><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><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><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><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><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><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><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><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><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><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><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><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><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](/en/v2/api-reference/introduction).</td></tr>
  </tbody>
</table>

## Conflict errors — 409

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: 'nowrap' }}>`TAG_ALREADY_EXISTS`</td><td>This tag is already applied to the conversation item. No action needed.</td></tr>
    <tr><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><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><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](/en/v2/api-reference/guides/error-handling#idempotency).</td></tr>
  </tbody>
</table>

## Rate limit errors — 429

<table>
  <thead>
    <tr><th>Code</th><th>Description</th></tr>
  </thead>

  <tbody>
    <tr><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><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><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><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><td style={{ whiteSpace: 'nowrap' }}>`INTERNAL_SERVER_ERROR`</td><td>An unexpected error occurred. Retry the request. If it persists, contact [support@withallo.com](mailto:support@withallo.com) with your `request_id`.</td></tr>
  </tbody>
</table>