# Errors

> The one error format, how to read it, and how to decide whether to retry. The full list of codes with cause and fix is in the error catalog.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/concepts/errors-overview/

Every error from the API has the same format (RFC 9457, content type `application/problem+json`). This is true for all errors: wrong key, unknown path, bad input, too many requests and problems on our side.

```json
{
  "type": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "title": "Missing permission",
  "status": 403,
  "error_type": "permission",
  "code": "insufficient_scope",
  "message": "This key lacks the permission 'contacts:write'.",
  "param": null,
  "retryable": false,
  "doc_url": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "request_id": "req_01JAB9C3X7K2M4N5P6Q7R8S9T0",
  "required_scope": "contacts:write"
}
```

## Fields

| Name | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes | URL of the documentation for this error. up to 300 characters |
| `title` | string | yes | Short title. up to 100 characters |
| `status` | integer | yes | HTTP status. 400 to 599 |
| `error_type` | string | yes | Stable error class. Branch on this first, then on code. one of: `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit`, `api` |
| `instance` | string | no | Path of the request that failed. up to 300 characters |
| `code` | string | yes | Stable error code from the error catalog. up to 60 characters |
| `message` | string | yes | English explanation. Contains no personal data. up to 500 characters |
| `param` | string or null | no | Path of the invalid field, for example body.tags[2]. up to 200 characters |
| `retryable` | boolean | yes | True if the same request may work later. |
| `doc_url` | string | yes | Link to the error page. up to 300 characters |
| `request_id` | string | yes | ID of the request, also in the Request-Id header. up to 40 characters |
| `errors` | array of object | no | All input errors when more than one field is invalid. up to 50 items |
| `errors[].param` | string | yes | Path of the field. up to 200 characters |
| `errors[].code` | string | yes | Error code. up to 60 characters |
| `errors[].message` | string | yes | English explanation. up to 500 characters |

Some errors add fields that belong to them, for example `required_scope`, `existing_id` or `limit`. Their meaning is explained under the code in the [error catalog](https://docs.smartchat.marketing/en/errors/).

## How to handle an error

1. Look at `error_type` first. It is one of `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit` or `api`. It never changes for a code.
2. Then look at `code`. Codes are stable. The `message` is for people; do not parse it.
3. If `retryable` is `true`, the same request may work later. For `rate_limited` wait for the seconds in `Retry-After`. Otherwise change the request.
4. Keep the `request_id`. If you need help, [write to support](https://docs.smartchat.marketing/en/support/) and include it.

## 400 and 422

- **400**: the request is not built correctly. For example the body is not JSON, a field is missing or unknown, or the cursor is broken.
- **422**: the request is built correctly, but its content breaks a rule. For example a phone number is not valid, or the contact has no opt-in.

## Several wrong fields

If more than one field is wrong, `errors` lists all of them in one answer, each with `param`, `code` and `message`. The `param` is the path of the field, for example `body.tags[2]`.

## Never an error you cannot trace

Error messages contain no personal data. If a connected service such as WhatsApp reports a problem, you get [`upstream_error`](https://docs.smartchat.marketing/en/errors/#upstream_error) with a short code, never the raw text of the other service.