API Reference

Reference

Error reference

When a request fails, check the HTTP status and use error.code or the five-digit error.numeric_code to identify the cause. error.message is for reading, not program logic. Keep request_id for troubleshooting.

400 Bad Request

  • invalid_request10000

    Check the JSON body and required fields.

  • invalid_provider30000

    Check the channel identifier in the URL.

  • unsupported_action30005

    This account action is not recognized; use a documented action.

  • invalid_conversation_type37000

    type must be user, group or channel.

  • unsupported_conversation_type37001

    The channel does not support this operation; choose a supported operation.

  • unsupported_message_type36000

    Choose a message.type supported by this channel.

  • unsupported_provider_auth_mode20018

    Choose an auth_mode supported by this channel.

  • auth_mode_phone_required20019

    Provide provider_data.phone when creating the account for this authorization mode.

  • invalid_reply_token36006

    The reply token cannot be read. Copy data.message.reply_token from the inbound event unchanged.

  • provider_invalid_request30001

    Check the channel-specific fields and formats.

  • create_api_key_failed11101

    The operation was rejected. Check the request and keep request_id for diagnosis.

  • update_api_key_failed11102

    The operation was rejected. Check the request and keep request_id for diagnosis.

  • rotate_api_key_failed11103

    The operation was rejected. Check the request and keep request_id for diagnosis.

  • update_workspace_failed41001

    The operation was rejected. Check the request and keep request_id for diagnosis.

401 Unauthorized

  • missing_api_key11000

    Add the X-Api-Key header.

  • invalid_api_key11001

    Check whether the API key is correct and enabled.

403 Forbidden

  • cors_forbidden11009

    The CORS origin, method or headers are not allowed. Check the calling environment.

404 Not Found

  • not_found10001

    Check the API path and method.

  • conversation_not_found37002

    The channel could not find this conversation; check the identifier and account.

  • contact_not_found35000

    The contact was not found under this account; check the identifier.

  • group_not_found34004

    The group was not found under this account; check the group ID.

409 Conflict

  • account_allocation_busy20011

    Account allocation is busy; retry after a short delay.

  • no_allocatable_server20013

    No capacity is available in this region; query regions for an allocatable option.

  • workspace_account_quota_exceeded20014

    The workspace messaging account limit has been reached; check usage and quota.

  • duplicate_provider_account20015

    This channel identity is already connected to another account in this workspace.

  • account_already_authorized20016

    The account is already authorized. Reuse it, or cancel authorization before starting a fresh flow.

  • account_binding_not_found30006

    The account has no active channel connection binding; check its status.

  • provider_account_mismatch20017

    The channel identity in the request does not match the account binding.

  • provider_not_ready30009

    The connection is not ready. Check authorization and runtime_status before retrying.

422 Unprocessable Entity

  • contact_not_found35000

    GET /contacts/info reported Conversation not found. Check the target identifier and the account used for the lookup.

500 Internal Server Error

  • create_account_failed20002

    Create account: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • update_account_failed20003

    Update account: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • delete_account_failed20004

    Delete account: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_account_failed20001

    Get account: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_accounts_failed20000

    List accounts: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_session_failed20005

    Get authentication state: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_auth_state_failed20006

    Get authentication state: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • run_action_failed20007

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • run_runtime_action_failed20008

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • run_session_action_failed20009

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • run_auth_action_failed20010

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • send_message_failed36001

    Send text message: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • pin_message_failed36002

    Pin / unpin message: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • revoke_message_failed36003

    Revoke message: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • react_message_failed36004

    React to message: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • edit_message_failed36005

    Edit message: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_conversations_failed37003

    List conversations: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_conversation_failed37004

    Get conversation: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_conversation_members_failed37005

    List conversation members: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • mark_conversation_read_failed37006

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • mark_conversation_unread_failed37007

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • mute_conversation_failed37008

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • unmute_conversation_failed37009

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • pin_conversation_failed37010

    Pin conversation: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • unpin_conversation_failed37011

    Unpin conversation: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_conversation_labels_failed37012

    List conversation labels: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • upsert_label_failed37013

    Create or update label: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • delete_label_failed37014

    Delete label: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • set_label_members_failed37015

    Add / remove label on conversations: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_contacts_failed35001

    List contacts: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_contact_failed35002

    Get contact: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • create_contact_failed35003

    Add contact: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_contact_membership_failed35004

    Check contact membership: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • block_contact_failed35005

    Block contact: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • unblock_contact_failed35006

    Unblock contact: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_blocklist_failed35007

    Get blocklist: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • set_contact_note_failed35008

    Set contact note: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_groups_failed34000

    List groups: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_group_failed34001

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • create_group_failed34002

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • leave_group_failed34003

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • update_group_members_failed34005

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • update_group_info_failed34006

    Update group info: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_group_join_requests_failed34007

    List group join requests: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • update_group_join_requests_failed34008

    Approve / reject join requests: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • set_group_join_approval_mode_failed34009

    Set group join approval mode: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_group_invite_code_failed34010

    Get group invite link: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_webhook_endpoints_failed40000

    The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • create_webhook_endpoint_failed40001

    Create webhook endpoint: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_webhook_endpoint_failed40002

    Get webhook endpoint: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • update_webhook_endpoint_failed40003

    Update webhook endpoint: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • deactivate_webhook_endpoint_failed40004

    Deactivate webhook endpoint: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • delete_webhook_endpoint_failed40005

    Delete webhook endpoint: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • get_workspace_failed41000

    Get current workspace: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_api_keys_failed11100

    List API keys: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

  • list_provider_regions_failed30011

    List provider regions: The service or channel could not complete this operation. Keep request_id and confirm the result before retrying writes.

501 Not Implemented

  • unsupported_by_provider30003

    The channel does not support this operation; choose a supported operation.

502 Bad Gateway

  • provider_adapter_not_found30004

    The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

  • provider_unavailable30002

    The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

503 Service Unavailable

  • allocation_service_unavailable20012

    Account allocation is temporarily unavailable; retry shortly.

Provider detail numeric codes

These codes refine a Provider cause without changing the original HTTP status or legacy code.

  • provider_operation_failed30010

    Provider operation failed

    The channel could not complete the operation. Keep request_id for diagnosis.

  • group_not_found34004

    Group not found

    The group could not be found. Some existing channel paths retain their original HTTP status and error.code.

  • group_not_participant34011

    Account is not participating in this group

    The group may exist, but this account is not a participant.