Error responses
REST API errors use the same JSON envelope. This page covers the shared format, status codes, and handling guidance for all operations.
{ "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
Section titled “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
Section titled “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:
{ "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 for trial and paid allowances and counting rules.
Retrying writes
Section titled “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 for key requirements, the 24-hour retry window, and how retries affect write allowances.