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

# Errors

> Error response format and common error codes.

All errors return a structured JSON body with a machine-readable `code` and a human-readable `message`.

## Error Format

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": {
      "name": ["Required field"]
    }
  }
}
```

| Field           | Type   | Description                                     |
| --------------- | ------ | ----------------------------------------------- |
| `error.code`    | string | Machine-readable error code                     |
| `error.message` | string | Human-readable explanation                      |
| `error.details` | object | Field-level validation errors (when applicable) |

## Error Codes

| Status | Code               | Description                                                                                 |
| ------ | ------------------ | ------------------------------------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Invalid request fields. Check `details` for specifics.                                      |
| 400    | `BAD_REQUEST`      | Malformed request body or invalid parameters.                                               |
| 401    | `UNAUTHORIZED`     | Missing or invalid API key.                                                                 |
| 404    | `NOT_FOUND`        | The requested resource does not exist or is not accessible.                                 |
| 409    | `CONFLICT`         | The request conflicts with the current state (e.g., starting a run on a deleted benchmark). |
| 429    | `RATE_LIMITED`     | Too many requests. Wait and retry.                                                          |
| 500    | `INTERNAL_ERROR`   | An unexpected error occurred on the server.                                                 |

## Handling Errors

Check the `code` field to determine how to respond programmatically:

```typescript theme={null}
try {
  const run = await verial.runs.create({ benchmarkId: 'invalid' })
} catch (err) {
  if (err.code === 'NOT_FOUND') {
    console.error('Benchmark not found')
  } else if (err.code === 'VALIDATION_ERROR') {
    console.error('Invalid request:', err.details)
  } else if (err.code === 'RATE_LIMITED') {
    // Wait and retry
    await sleep(parseInt(err.retryAfter ?? '60', 10) * 1000)
  } else {
    throw err
  }
}
```

## Rate Limiting

The API enforces rate limits per API key. When you exceed the limit, you receive a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

## Validation Errors

Validation errors include a `details` object that maps field names to arrays of error messages:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": {
      "name": ["String must contain at least 1 character(s)"],
      "timeout": ["Number must be greater than 0"]
    }
  }
}
```