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

# Errors & request IDs

> Every Oviond API response uses one consistent JSON envelope. Learn the error shape, the status codes, and how to use request IDs when contacting support.

Every Oviond API response — success or failure — uses the same JSON envelope, so your client can parse one shape everywhere. All fields are `snake_case`.

## Success envelope

```json theme={null}
{
  "success": true,
  "data": { "...": "..." },
  "meta": { "request_id": "req_a1b2c3" }
}
```

List endpoints add pagination fields to `meta`. See [Pagination, filtering & sorting](/api/concepts/pagination).

## Error envelope

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Client not found",
    "status_code": 404
  },
  "meta": { "request_id": "req_a1b2c3" }
}
```

Every error returns this shape with the matching HTTP status — including `401` and `403`. There are no plain-text error bodies.

### Validation errors

`400` and `422` responses add a `details` object with per-field messages, so you can surface exactly which field failed:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Validation error",
    "status_code": 422,
    "details": [
      { "path": ["name"], "message": "Required" }
    ]
  },
  "meta": { "request_id": "req_a1b2c3" }
}
```

## Status codes

| Code  | Meaning                                                                        |
| ----- | ------------------------------------------------------------------------------ |
| `200` | Success                                                                        |
| `201` | Created                                                                        |
| `204` | No content (successful delete)                                                 |
| `400` | Bad request — malformed body or parameters                                     |
| `401` | Unauthorized — missing, malformed, invalid, or revoked credential              |
| `403` | Forbidden — valid credential without permission, or your plan lacks API access |
| `404` | Not found — the resource doesn't exist, or isn't in your account               |
| `422` | Validation error — see `error.details`                                         |
| `429` | Too many requests — see [Rate limits & retries](/api/concepts/rate-limits)     |
| `500` | Server error — safe to retry with backoff                                      |

<Note>
  A `404` is also returned when a resource exists but belongs to a different account — Oviond never reveals whether an ID exists outside your tenant.
</Note>

## Request IDs

Every response includes an `X-Request-Id` header, and every error repeats it as `meta.request_id`. If you send your own `X-Request-Id`, Oviond preserves it so you can correlate requests across your systems and ours.

```bash theme={null}
curl -i https://api.oviond.com/v1/users/me \
  -H "Authorization: Bearer YOUR_API_KEY"
# ...
# X-Request-Id: req_a1b2c3
```

When something looks wrong, capture the `request_id` and include it when you contact support — it lets us find the exact request in our logs.