> ## Documentation Index
> Fetch the complete documentation index at: https://chatobserver.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I handle chatobserver API errors and rate limits?

> Interpret authentication, validation, conflict, and rate-limit responses, and retry API requests safely.

Use the HTTP status and structured error code to choose the next action. Correct authentication, permission, and validation problems before retrying. For rate limits and retryable service failures, respect the response's retry guidance.

| Status | Meaning                                        | Action                                                       |
| ------ | ---------------------------------------------- | ------------------------------------------------------------ |
| 400    | The request is invalid                         | Correct the identified parameter or payload field            |
| 401    | Authentication failed                          | Check the credential and authentication header               |
| 403    | The credential lacks access                    | Review scopes, service-account requirements, and permissions |
| 404    | The resource is unavailable to this credential | Check its identifier and workspace                           |
| 409    | The request conflicts with current state       | Read the error code before repeating a mutation              |
| 429    | A request limit was reached                    | Wait according to `Retry-After`                              |
| 5xx    | A service failure occurred                     | Retry only when safe, with bounded backoff                   |

## Rate-limit headers

Public API limits apply per key and per workspace: 120 requests per minute for an individual key and 600 per minute across a workspace's keys. The versioned API rate-limit buckets apply these limits to their respective API version.

Responses expose `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. The reset value is a Unix timestamp in seconds. A 429 response includes `Retry-After` in seconds. Creating extra keys does not remove the workspace ceiling.

## Error formats

Visibility errors normally contain `error.code`, `error.message`, optional `error.details`, and a top-level `requestId`.

Data domain errors use `error.code`, `error.requestId`, `error.retryable`, `error.retryAfterSeconds`, `error.fieldPath`, `error.parameters`, and `error.repairActions`. Authentication and outer rate-limit failures on Data routes can use the visibility error envelope. Handle both shapes.

Include the request reference when contacting support. Do not log the credential. Read [safe writes](/docs/developers/safe-writes) before automatically retrying a request that creates or changes data.