# Error responses

REST API errors use the same JSON envelope. This page covers the shared format, status codes, and handling guidance for all operations.

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request fields",
    "requestId": "request_example"
  }
}
```

| Field             | Meaning                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------ |
| `error.code`      | Machine-readable error code. Use this and the HTTP status to decide how to handle a failure.                 |
| `error.message`   | Human-readable explanation. Do not depend on its exact wording.                                              |
| `error.requestId` | Server-generated identifier, also returned in the `X-Request-Id` header. Include it when reporting an issue. |
| `error.details`   | Present for `daily_limit_exceeded`; describes the exhausted allowance.                                       |

## Status codes

| Status | Error code                             | Meaning and action                                                                                                                                                                                        |
| ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`, `invalid_cursor`    | Fix malformed JSON, repeated query parameters, an invalid or missing `Idempotency-Key`, or a cursor that does not match the request. JSON writes require `Content-Type: application/json`.                |
| 401    | `invalid_credentials`                  | Supply a valid workspace API key in `Authorization: Bearer YOUR_API_KEY`. The response includes `WWW-Authenticate: Bearer`.                                                                               |
| 402    | `workspace_paused`, `limit_exceeded`   | The workspace is paused, or a workspace resource limit such as the 50-webhook maximum is reached. Resume the workspace or remove resources before retrying. Internal notes remain available while paused. |
| 403    | `permission_denied`                    | The key lacks a required permission. Check the operation's scopes; write scopes do not imply read scopes.                                                                                                 |
| 404    | `not_found`                            | The resource is unavailable in this workspace. Check identifiers and user selectors.                                                                                                                      |
| 409    | `conflict`                             | The request conflicts with existing state or reuses an idempotency key with different input. Resolve the conflict before retrying.                                                                        |
| 410    | `event_cursor_expired`                 | The event cursor has expired. Resynchronize resources and start polling with a new cursor.                                                                                                                |
| 413    | `payload_too_large`                    | Reduce the JSON request body to at most 64 KiB. This also applies to streamed requests.                                                                                                                   |
| 422    | `validation_failed`                    | Fix invalid fields or unknown query parameters using the operation's request schema.                                                                                                                      |
| 429    | `rate_limited`, `daily_limit_exceeded` | Wait at least the number of seconds in `Retry-After`. See the limits guidance below.                                                                                                                      |
| 500    | `internal_error`                       | An unexpected server error occurred. Retry with backoff; retain the request ID if the problem persists.                                                                                                   |

## Rate limits and write allowances

For `rate_limited`, `Retry-After` is 60 seconds. Rate limits can apply to authentication attempts, an API key, a workspace, or a user.

Each user accepts at most 30 messages and notes per minute across all of their conversations, and at most 10 per minute from any one sender. These limits apply to every channel, so messages from the Messenger, email, and the dashboard count too. A message or note rejected by them has already used its message allowance; retry with the same `Idempotency-Key` after `Retry-After` so it is not consumed again.

Write allowances count admitted writes over a rolling 24 hours, measured in hourly buckets. For `daily_limit_exceeded`, `Retry-After` is the number of seconds until `retryAt`. The response includes details:

```json
{
  "error": {
    "code": "daily_limit_exceeded",
    "message": "API messages limit for the last 24 hours reached",
    "requestId": "request_example",
    "details": {
      "resource": "messages",
      "limit": 200,
      "used": 200,
      "retryAt": "2026-10-14T09:00:00.000Z"
    }
  }
}
```

`resource` is `users`, `conversations`, or `messages`. `limit` is the allowance per rolling 24 hours, `used` is the amount admitted in the last 24 hours, and `retryAt` is the earliest time enough older writes leave the window for usage to drop below the limit. Allowances are shared across all API keys in the workspace. See [usage limits](/docs/api-reference/#limits) for trial and paid allowances and counting rules.

## Retrying writes

After a timeout or retryable error, reuse the same `Idempotency-Key` and request body. Respect `Retry-After` on `429` responses and use backoff for transient failures. Fix validation, permission, and conflict errors before retrying.

See [idempotent requests](/docs/api-reference/idempotent-requests/) for key requirements, the 24-hour retry window, and how retries affect write allowances.
