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

# API Error Codes and Responses

> Reference the standard error response format and complete list of Xobito API error codes, including validation errors.

## HTTP status code summary

| Status | Meaning | What it means |
| - | - | - |
| `200` | OK | Everything worked as expected. |
| `400` | Bad Request | The request body isn't valid JSON. |
| `401` | Unauthorized | Your `x-api-key` is missing, isn't recognized, or has been revoked or has expired. |
| `402` | Payment Required | Your organization has no active subscription for this feature. |
| `404` | Not Found | The `id` in the URL doesn't match anything in your organization. |
| `409` | Conflict | The record you're creating already exists (e.g. a duplicate phone number, or an open chat that's already there). |
| `422` | Unprocessable | The request is valid JSON, but fails validation — a missing field, a bad value, an out-of-range number. `error` in the response lists exactly what's wrong. |
| `500` | Server Error | Something went wrong on Xobito's side. Try again, and contact support if it keeps happening. |

> [!NOTE]
>
> A missing, unknown, revoked, or expired `x-api-key` returns `401` with a specific `code`, listed below. Older builds returned `500` for these cases, so if you still see a `500` on a request you didn't expect, check your API key first.

## Response shape

Every response — success or error — shares one envelope. On success, `data` holds the payload. On error, `success` is `false` and there's no `data`:

```json 200 — success theme={null}
{
  "success": true,
  "code": "HC-1",
  "name": "success_200",
  "message": "Request was successful.",
  "data": { }
}
```

```json 422 — error theme={null}
{
  "success": false,
  "code": "HC-10",
  "http_code": 422,
  "name": "error_422",
  "message": "Please check your inputs.",
  "error": ["Name is required."]
}
```

**success** `boolean`

`true` on every `2xx`, `false` otherwise.

**http\_code** `integer`

Present on errors only — mirrors the real HTTP status shown in the table above.

**message** `string`

A human-readable summary — safe to show a user as-is.

**error** `array`

Present only on `422` — one plain-English string per invalid field.

**code** `string`

An internal code, e.g. `HC-1`. See the note below before matching on this.

**name** `string`

A machine-readable name, e.g. `error_422` or a route-specific `validation.xxx_not_found`.

> [!NOTE]
>
> `code` isn't the same for the same kind of error across every route — a "not found" alone shows up as three different `code` values depending on which endpoint you called. **Build your error handling around `http_code`, not `code`.** See [Error code reference](#error-code-reference) below only if you need to distinguish the exact cause.

## Errors that send calls don't return

The three send calls ([template](https://xobito.com/docs/api-docs/send-messages/send-template), [service message](https://xobito.com/docs/api-docs/send-messages/send-service-message), [canned response](https://xobito.com/docs/api-docs/send-messages/send-canned-response.md)) are asynchronous. They return an error only for a bad request (`422`), a bad key or subscription (`401`, `402`), or an unknown channel, template or canned response (`404`). Everything else is checked after the `200` has been sent, so a failure there is **not returned to you**. The message isn't sent, no message record is saved, and no webhook fires.

> [!NOTE]
>
> **A chatbot or AI agent on the chat does not block your send.** The message is queued and sent as normal, and the chatbot or AI agent keeps running: your send does not pause or end it. The customer can get your message and the automation's reply close together. To stop the automation first, take over the chat in [Chat](https://xobito.com/docs/chat/conversation.md).

## Error code reference

For when you need the exact `code`/`name` a specific route returns — every row below is a real, captured response.

### 400 Bad Request

| `code` | `name` | `message` |
| - | - | - |
| `HC-4` | `error_400` | Bad request. |
| `CH-14` | `validation.not_starrable` | Only a WhatsApp message can be starred. |
| `CH-6` | `validation.invalid_phone_number` | `to` isn't a valid phone number. |
| `CH-11` | `validation.channel_mismatch` | The chat belongs to a different channel than `channel_id`. |
| `CH-19` | `validation.canned_response_channel_mismatch` | The canned response is limited to a different channel than `channel_id`. |

### 401 Unauthorized

| `code` | `name` | `message` |
| - | - | - |
| `C-8` | `header_missing` | Required header is missing. (No `x-api-key` header was sent.) |
| `C-22` | `invalid_api_key` | The provided API key is not valid. |
| `C-23` | `api_key_revoked` | This API key has been revoked or has expired. |

### 402 Payment Required

| `code` | `name` | `message` |
| - | - | - |
| `C-10` | `payment_required` | This feature requires an active subscription. Please upgrade your plan to continue. |
| `C-15` | `organization_not_found` | Organization not found. |

### 404 Not Found

| `code` | `name` | `message` |
| - | - | - |
| `C-1` | `data_not_found` | Requested data is not available. |
| `CT-1` | `validation.not_found` | Record not found. |
| `CH-1` | `validation.not_found` | Record not found. |
| `CH-2` | `validation.channel_not_found` | Channel not found. (Send calls: `channel_id` doesn't match a channel in your organization.) |
| `CH-3` | `validation.contact_not_found` | Contact not found. |
| `CH-7` | `validation.chat_not_found` | Chat not found. |
| `CH-8` | `validation.template_not_found` | Template not found. (Send a template: no template with that `name` and `language` on that channel.) |
| `CH-9` | `validation.canned_response_not_found` | Canned response not found. (Send a canned response: `id` doesn't match a canned response.) |
| `ACT-4` | `validation.custom_object_field_not_found` | The custom object has no field with this `field_id`. (Custom object field routes.) |
| `ORG-20` | `validation.<resource>_not_found` | `<Resource>` not found — confirmed for `canned_response`, `conversation_stage`, `custom_field`, `department`, `label`, `pipeline_stage`, `role`, `tag`. |

### 409 Conflict

| `code` | `name` | `message` |
| - | - | - |
| `CH-5` | `validation.chat_already_exist` | An open chat already exists for this contact on this channel. |
| `CH-29` | `validation.schedule_not_editable` | The scheduled message can no longer be changed (already sent, failed, cancelled, or being sent). |
| `CM-1` | `validation.not_found` | A catalog or product `id` doesn't match anything in your organization. (Commerce routes.) |
| `CM-2` | `validation.catalog_not_writable` | The catalog isn't owned by your business, so you can't add or change products in it. |
| `CM-3` | `validation.catalog_not_readable` | The catalog can't be read with your access. |
| `CM-4` | `validation.catalog_not_bound` | The catalog isn't linked to a WhatsApp number, so Xobito can't write the product to Meta. Link the catalog to a number first. |
| `CH-32` | `validation.channel_catalog_not_bound` | The channel has no catalog bound to it. (Send or schedule a product message, a product carousel, or a product template header without a `catalog_id`.) Bind a catalog to the channel, or pass `catalog_id`. |
| `CT-4` | `validation.phone_already_exists` | A contact with this phone number already exists. |
| `ACT-2` | `validation.custom_object_already_exists` | Another custom object already uses this name or key. (Create or update a custom object.) |
| `ACT-3` | `validation.custom_object_field_already_exists` | Two fields in the same custom object share a key. (Create a custom object, or add a field.) |
| `FL-7` | `validation.flow_deprecate_in_use` | This Flow cannot be deprecated because it is currently associated with a template or canned response. Remove those associations first. |

### 422 Validation failed

| `code` | `name` | `message` |
| - | - | - |
| `HC-10` | `error_422` | Please check your inputs. |
| `CH-30` | `validation.authentication_template_not_allowed` | Authentication (one-time code) templates can't be scheduled. |

### Broadcast errors

These come from the [Broadcasts](https://xobito.com/docs/api-docs/broadcasts/send-broadcast-contacts.md) routes. The status code differs by error, so each row has its own.

| Status | `code` | `name` | `message` |
| - | - | - | - |
| 404 | `BC-1` | `validation.not_found` | Record not found. |
| 404 | `BC-2` | `validation.channel_not_found` | Channel not found. |
| 404 | `BC-7` | `validation.template_not_found` | One of the referenced templates could not be found. |
| 409 | `BC-22` | `validation.halt_acknowledge_required` | The system paused this broadcast. Confirm you have reviewed the reason to resume it. |
| 422 | `BC-3` | `validation.channel_not_connected` | Channel is not connected. |
| 422 | `BC-4` | `validation.schedule_at_required` | Schedule time is required. |
| 422 | `BC-5` | `validation.template_required` | Template is required. |
| 422 | `BC-8` | `validation.invalid_status_transition` | This status change is not allowed from the broadcast's current status. |
| 422 | `BC-10` | `validation.audience_limit_exceeded` | The combined manual audience selection cannot exceed 1000 recipients. |
| 422 | `BC-11` | `validation.authentication_template_not_allowed` | Authentication-category templates cannot be used in a broadcast. |
| 422 | `BC-12` | `validation.template_variable_required` | Every template variable must have a mapped value or fallback before publishing. |
| 422 | `BC-13` | `validation.organization_timezone_required` | Organization timezone must be configured before scheduling a broadcast. |
| 422 | `BC-14` | `validation.schedule_at_in_past` | Schedule time cannot be in the past. |
| 422 | `BC-15` | `validation.audience_file_required` | An uploaded audience file is required for this audience type. |
| 422 | `BC-18` | `validation.audience_file_empty` | The uploaded audience file has no usable recipients. |
| 422 | `BC-20` | `validation.batch_settings_incomplete` | Batch settings are incomplete: unit, time, recipients per run and timezone are required. |
| 422 | `BC-21` | `validation.batch_days_required` | Select at least one day for a weekly batch. |
| 422 | `BC-23` | `validation.audience_empty` | The audience has no recipients. Add at least one before publishing. |
| 422 | `BC-26` | `validation.recurring_settings_incomplete` | Recurring settings are incomplete: unit, time of day and timezone are required, and a monthly or yearly Nth-weekday rule needs exactly one weekday. |
| 422 | `BC-27` | `validation.recurring_stop_required` | Choose when the series ends: a stop date or a number of runs. |
| 422 | `BC-28` | `validation.recurring_no_run` | With these settings the series would never run. Check the start, the repeat rule and the stop rule. |
| 422 | `BC-31` | `validation.audience_file_missing_country_code` | The audience file has no country code column. |
| 422 | `BC-32` | `validation.audience_file_missing_phone` | The audience file has no phone number column. |
| 503 | `BC-25` | `validation.dispatch_unavailable` | The broadcast could not be handed to the sending queue right now. Please try again. |

### 500 Internal server error

| `code` | `name` | `message` |
| - | - | - |
| `HC-12` | `error_500` | Internal server error. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.