---
title: "Errors"
method: GET
path: "/guides/errors"
tags: ["Errors"]
---

# Errors

`GET /guides/errors`

## Request

- Base URL: `https://developers.chatway.app/api/v1`
- URL: `https://developers.chatway.app/api/v1/guides/errors`
- Auth: none required

# 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:

```json
{
  "message": "Conversation not found"
}
```

### Validation error (`422`)

When query or body parameters fail validation:

```json
{
  "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:

```json
{
  "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:

```json
{
  "message": "Conversation not found"
}
```

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

```json
{
  "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](#validation-error-422) 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:

```json
{
  "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:

```json
{
  "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

## Response `200`

Documentation.

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)