Skip to content

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 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.

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.

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.