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

# Errors

> HTTP error codes and error response format

## Response format

All error responses follow the same shape:

```json theme={null}
{
  "message": "Human-readable error message",
  "errors": []
}
```

`errors` is an array of field-level validation errors when applicable (e.g. request body validation failures). It is empty for most errors.

***

## HTTP status codes

| Code  | Name                  | When it occurs                                                                         |
| ----- | --------------------- | -------------------------------------------------------------------------------------- |
| `400` | Bad Request           | Missing required field, invalid ObjectId, batch too large, invalid parameter value     |
| `401` | Unauthorized          | Missing or invalid API key / session cookie                                            |
| `403` | Forbidden             | API key doesn't have access to the workspace; agent not in workspace                   |
| `404` | Not Found             | Dataset, run, trace, or agent not found                                                |
| `409` | Conflict              | Run is already in a terminal state (`completed` or `failed`); analysis already running |
| `429` | Too Many Requests     | Rate limit exceeded (see [Rate Limits](#rate-limits))                                  |
| `500` | Internal Server Error | Unexpected server error                                                                |

***

## Common errors

### 401 Unauthorized

```json theme={null}
{ "message": "Unauthorized", "errors": [] }
```

Check that:

* Your `x-api-key` header is present and matches a valid workspace API key
* The key hasn't been revoked in **Settings → API Keys**

### 403 Forbidden

```json theme={null}
{ "message": "Could not resolve a valid workspace", "errors": [] }
{ "message": "Unauthorized workspace access", "errors": [] }
{ "message": "Agent not found in workspace or insufficient permissions", "errors": [] }
```

The API key is valid, but it doesn't have the required access. Verify the `workspaceId` belongs to the same workspace as your API key.

### 404 Not Found

```json theme={null}
{ "message": "Dataset not found", "errors": [] }
{ "message": "Run not found", "errors": [] }
```

The requested resource doesn't exist or belongs to a different workspace.

### 409 Conflict — terminal state

```json theme={null}
{ "message": "Run is already in a terminal state", "errors": [] }
```

Returned by `POST /results` when the run has already been finalized or failed. Check the run status with `GET /runs/:id` before submitting more results.

### 400 Bad Request

```json theme={null}
{ "message": "batchId is required", "errors": [] }
{ "message": "results must be a non-empty array", "errors": [] }
{ "message": "Batch size must not exceed 10", "errors": [] }
{ "message": "Each question must have main_question.query", "errors": [] }
{ "message": "CI/CD is not enabled for this dataset", "errors": [] }
```

***

## Rate limits

| Route group                        | Limit                             |
| ---------------------------------- | --------------------------------- |
| `POST /ingest/traces`              | 300 requests / minute per API key |
| `POST /ingest/ci-runs/*`           | 60 requests / minute per API key  |
| `POST /custom-agent-evaluations/*` | 60 requests / minute per API key  |

When a rate limit is hit, the response is `429 Too Many Requests`. Wait for the next minute window and retry.

***

## Retrying

Safe to retry on `500` and `429`. **Not** safe to retry `POST /results` without idempotency keys — always set `idempotencyKey` on every result to avoid duplicate scoring on retry.