Error codes

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.
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.

​

Validation errors — 400

Code	Description
INVALID_REQUEST_BODY	The request body could not be parsed. Ensure Content-Type is application/json and the body is well-formed JSON.
MISSING_PARAMETER	A required query parameter is missing. Add the parameter named in the param field.
MISSING_HEADER	A required header is missing. Add the header named in the param field.
UNSUPPORTED_MEDIA_TYPE	The Content-Type is not supported. Use application/json. Returns 415.
INVALID_PAGE_SIZE	The size parameter value is invalid. Provide a numeric value between 1 and 100.
INVALID_SEARCH_QUERY	The search parameter must contain at least one alphanumeric character. Special characters are stripped automatically — provide plain-text keywords (e.g., "john" or "missed call"). Words are combined with AND and prefix-matched.
MISSING_ALLO_NUMBER	The allo_number parameter is required. Add it to your request. List your numbers with GET /v2/api/numbers.
INVALID_DATE_RANGE	The date range is invalid: from must be before to. Use YYYY-MM-DD format.
DATE_RANGE_TOO_WIDE	The date range exceeds the maximum allowed number of days. Narrow your date range.
INVALID_ITEM_ID	Item ID has an unrecognized prefix. Use IDs from the conversations API: cll- for calls, msg- for messages.
BATCH_TOO_LARGE	Batch size exceeds the maximum of 100. Split your request into batches of 100 or fewer.
TAGS_REQUIRED	At least one tag is required. Provide a non-empty tags array. List available tags with GET /v2/api/tags.
INVALID_ACTION	Unknown action value. Use one of: READ, UNREAD, ARCHIVE, UNARCHIVE.
INVALID_GRANULARITY	Unknown granularity value. Use one of: DAY, WEEK, MONTH.
INVALID_GROUP_BY	Unknown group_by value. Check the suggestion field for allowed values.
UNSUPPORTED_EXTEND_VALUE	Unknown extend value. Currently supported: transcript.
METHOD_NOT_ALLOWED	HTTP method not supported for this endpoint. Check the suggestion field for supported methods. Returns 405.
INVALID_PHONE_FORMAT	Phone number is not valid E.164 format. Use format: +14155551234 (+ prefix, country code, no spaces or dashes).
INVALID_TO_NUMBER	The destination number is invalid or cannot be reached. Provide a valid E.164 phone number.
TO_NUMBER_COUNTRY_MISMATCH	Cross-country SMS is not supported for this number. Use a phone number in the same country as the recipient.
NUMBER_NOT_SMS_ENABLED	This number does not have outbound SMS enabled. Enable SMS in the dashboard, or use a different number from GET /v2/api/numbers.
SENDER_ID_INBOX_CANNOT_SEND_SMS	Sender ID inboxes cannot send SMS messages. Use a regular phone number instead.
SENDER_ID_NOT_ACTIVE	The sender ID is not active. Activate the sender ID in the Allo dashboard before sending.
MESSAGE_NOT_COMPLIANT	Message content does not comply with messaging compliance rules. Remove disallowed content and retry.
LANDLINE_NUMBER_NOT_SUPPORTED	The destination number is a landline and cannot receive SMS. Provide a mobile phone number instead.
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	Not a URL that can be scraped. Send an absolute http(s) URL of a publicly reachable page.
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.

​

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 with this ID on the line’s AI receptionist. 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.

​

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 AI receptionist already has a knowledge entry for this URL. Reuse the existing entry.
AGENT_KNOWLEDGE_LIMIT_REACHED	The AI receptionist already holds the maximum of 5 websites. Delete one first.
AGENT_LINE_NOT_ASSIGNED	The line has no phone number assigned, so its AI receptionist can neither answer nor forward.

​

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_KNOWLEDGE_SCRAPE_FAILED	The page could not be read. Always retryable: true. Retry in a few seconds and check the page is publicly reachable.
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.