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:

Example:

{
  "message": "Unauthenticated."
}

What to do: create or rotate a key under Settings → Developer Tools → API Keys and send it in X-API-KEY.

403 Forbidden

Meaning: the request was authenticated, but this account cannot use the API.

Example (team without an active paid plan or trial):

{
  "message": "API access requires an active paid plan or trial. Upgrade your plan to use the API."
}

401 vs 403: use 401 when the key is missing or not recognized. Use 403 when the key is valid but the workspace is not eligible for API access.

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:

429 Too Many Requests

Meaning: rate limit exceeded for your API key.

Body:

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

Response headers:

Header Description
Retry-After Seconds to wait before retrying (when provided by the rate limiter)

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 with backoff. If the error persists, contact support with the details listed at the top of this page.

Related pages