# Error handling

> Handle API errors by status and machine-readable error code.

Breadcrumb: API › Error handling · Updated: 2026-10-17
Docs index: https://docs.cevoid.com/developers/llms.txt

API errors include an HTTP status, a stable `code`, a human-readable `message`, and optional debugging details. Use the status for broad handling and `code` for specific recovery behavior.

## Error response

```json
{
  "status": 422,
  "code": "validation_error",
  "message": "Request validation failed",
  "request_id": "req_abc123",
  "additional_data": {
    "errors": [
      {
        "field": "query.limit",
        "message": "Too big: expected number to be <=100"
      }
    ]
  }
}
```

| Field | Meaning |
| --- | --- |
| `status` | HTTP status code |
| `code` | Stable error code for programmatic handling |
| `message` | Human-readable summary |
| `request_id` | Request identifier for support and debugging |
| `additional_data` | Optional details such as field validation errors |

## Status codes

| Status | Meaning | Action |
| --- | --- | --- |
| `400` | Invalid request | Check the request syntax. |
| `401` | Invalid or missing key | Verify the key with `/v2/me`. |
| `403` | Missing permission | Create a key with the required scope. |
| `404` | Resource not found | Check the path and resource ID. |
| `422` | Validation failed | Fix the fields listed in `additional_data`. |
| `429` | Rate limit exceeded | Wait for `Retry-After` before retrying. |
| `500` | Server error | Retry conservatively with backoff. |

See [Rate limits](https://docs.cevoid.com/developers/api/rate-limits.md) for throttling behavior.

## Handle errors in code

```javascript
const response = await fetch('https://api.cevoid.com/v2/posts?limit=250', {
  headers: { Authorization: `Bearer ${process.env.CEVOID_API_KEY}` }
});

if (!response.ok) {
  const error = await response.json();

  console.error({
    status: error.status,
    code: error.code,
    message: error.message,
    requestId: error.request_id
  });
}
```

Log `request_id` for every failed request. Do not retry `401`, `403`, `404`, or `422` until you change the request.

---

Canonical: https://docs.cevoid.com/developers/api/errors