Errors

All Chatway REST API errors return JSON with a message field. Validation failures also include an errors object with field-specific messages.

There is no request or trace ID in error responses today. When contacting support, include the UTC timestamp, HTTP method, path, status code, and full response body.

Response shape

Standard error

Most errors use this shape:

{
  "message": "Conversation not found"
}

Validation error (422)

When query or body parameters fail validation:

{
  "message": "The limit must be an integer.",
  "errors": {
    "limit": [
      "The limit must be an integer."
    ]
  }
}

Multiple fields may appear under errors. The top-level message is usually the first validation failure.

Status codes

401 Unauthorized

Meaning: the request is not authenticated.

Common causes:

• Missing X-API-KEY header
• Invalid or revoked API key

Example:

{
  "message": "Unauthenticated."
}

What to do: check that X-API-KEY contains the intended key, without extra spaces, and that the key has not been revoked. If you need a replacement, create one under Settings → Developer Tools → API Keys. Do not put the key in logs or support screenshots.

403 Forbidden

Meaning: the request was authenticated, but the key is not allowed to perform this action (for example, the resource belongs to another workspace).

401 vs 403: use 401 when the key is missing or not recognized. Use 403 when the key is valid but the action is not permitted.

404 Not Found

Meaning: the route or resource does not exist for your workspace.

Examples:

{
  "message": "Conversation not found"
}

{
  "message": "Resource not found."
}

{
  "message": "Not found."
}

What to do: confirm the ID (from a webhook payload or a list endpoint), that the resource belongs to your workspace, and that the path is correct.

422 Unprocessable Entity

Meaning: validation failed on query parameters or JSON body.

See Validation error above.

Common cases:

• limit above the maximum for that endpoint
• Missing required body fields (for example conversation_id on POST /messages)
• Invalid field filter names in include_fields or exclude_fields

Read the errors object to find the rejected fields. Correct those values before retrying; repeating an unchanged request will not fix a validation error. Check the operation's own page for its required fields, allowed filter names and page-size limit.

429 Too Many Requests

Meaning: rate limit exceeded for your API key.

Body:

{
  "message": "Too many requests."
}

Response headers:

The public API allows 60 requests per minute per API key. See Rate limits for backoff guidance.

500 Internal Server Error

Meaning: an unexpected server error.

Example:

{
  "message": "Server Error"
}

What to do: retry reads after a delay, with a maximum retry count. For writes, first check whether the intended change occurred, especially after a timeout. If failures continue, contact support with the UTC time, method, path, status and a redacted response body.

Related pages

• Rate limits: per-key limits and retry behavior
• Customer support: what to send when you need help
• Quickstart: authentication and first request