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

# Error Codes

> Complete reference of HTTP status codes and error responses returned by the MetrixLLM gateway.

The MetrixLLM gateway returns standard HTTP status codes with structured JSON error bodies. This reference covers all possible error responses.

## 4xx Client Errors

### 400 Bad Request

The request body is malformed or contains invalid parameters.

```json theme={null}
{
  "error": "Invalid request format"
}
```

**Common causes:**

* Missing required fields (`model`, `messages`)
* Invalid JSON syntax
* Unsupported parameters for the target provider

***

### 401 Unauthorized

The API key is missing, invalid, or has been revoked.

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

**Common causes:**

* Missing `Authorization` header
* API key doesn't start with `sk-metrix-`
* API key has been deleted or deactivated
* Key hash doesn't match any active key in the database

***

### 402 Payment Required

The workspace has insufficient credits or has exceeded its budget cap.

```json theme={null}
{
  "error": "Insufficient operational platform credits on workspace ledger. Top up required."
}
```

**Common causes:**

* Monthly budget cap reached
* Prepaid credit balance depleted
* Workspace billing overdue

***

### 403 Forbidden

The request is blocked by workspace security policies.

```json theme={null}
{
  "error": "IP address not allowed. This workspace has an IP allowlist enabled."
}
```

**Other 403 variants:**

| Error message                                   | Cause                                      |
| :---------------------------------------------- | :----------------------------------------- |
| `This workspace has been permanently disabled.` | Workspace has been soft-deleted            |
| `Workspace not found.`                          | Workspace ID doesn't exist in the database |
| `IP address not allowed...`                     | Client IP not in the workspace's allowlist |

***

### 404 Not Found

The requested resource doesn't exist.

```json theme={null}
{
  "error": "Route not found"
}
```

**Common causes:**

* Requested endpoint doesn't exist (e.g. `/v1/unknown-endpoint`)
* Batch ID not found in `/v1/batches/:id/results`

***

### 413 Payload Too Large

The request body exceeds the gateway's 2MB limit.

```json theme={null}
{
  "error": "Request body too large"
}
```

***

### 429 Too Many Requests

A rate limit has been exceeded.

```json theme={null}
{
  "error": "Rate limit exceeded: Workspace RPM Limit (global)",
  "limit": 100,
  "current": 101,
  "window": "fixed_minute",
  "rule_id": "abc123",
  "retry_after": 45
}
```

See [Rate Limits](/docs/rate-limits) for full details on rate limit headers and configuration.

***

## 5xx Server Errors

### 500 Internal Server Error

An unexpected error occurred within the gateway.

```json theme={null}
{
  "error": "Failed to create batch record",
  "type": "internal_error",
  "code": "BATCH_CREATE_FAILED"
}
```

**Error codes:**

| Code                        | Description                                 |
| :-------------------------- | :------------------------------------------ |
| `DB_CONNECTION_FAILED`      | Database connection pool exhausted          |
| `BATCH_CREATE_FAILED`       | Failed to insert batch record into database |
| `BATCH_FETCH_FAILED`        | Failed to retrieve batch from database      |
| `BATCH_RESULTS_LOAD_FAILED` | Failed to load batch results                |
| `BATCH_PROCESSING_FAILED`   | Batch processing encountered a fatal error  |
| `BATCH_LIST_FAILED`         | Failed to list batches for workspace        |

***

### 502 Bad Gateway

The upstream LLM provider returned an invalid response or is unreachable.

```json theme={null}
{
  "error": "Malformed JSON response from provider",
  "type": "upstream_error",
  "code": "PROVIDER_CONNECTION_FAILED"
}
```

**Common causes:**

* Provider API returned non-JSON response
* Network timeout connecting to provider
* Provider returned an unexpected response format

***

### 503 Service Unavailable

All providers in the fallback chain are down or the circuit breaker is open.

```json theme={null}
{
  "error": "All providers failed. Last error: 503 from openai",
  "type": "provider_error",
  "code": "ALL_PROVIDERS_FAILED"
}
```

***

## Provider-Specific Errors

When a provider returns an error, the gateway forwards it with the original status code:

### OpenAI errors

```json theme={null}
{
  "error": {
    "message": "Invalid model specified",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

### Anthropic errors

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid model specified"
  }
}
```

### Google Gemini errors

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid value",
    "status": "INVALID_ARGUMENT"
  }
}
```

***

## Batch API Errors

| Status | Code                       | Description                                        |
| :----- | :------------------------- | :------------------------------------------------- |
| 400    | `BATCH_EMPTY`              | Requests array is empty                            |
| 400    | `WEB_SEARCH_NOT_SUPPORTED` | Web search cannot be used in batch mode            |
| 400    | `PROVIDER_NOT_SUPPORTED`   | Batch API not available for this provider          |
| 404    | `BATCH_NOT_FOUND`          | Batch ID doesn't exist                             |
| 409    | `BATCH_IN_PROGRESS`        | Batch is still processing (returns `202 Accepted`) |

***

## Circuit Breaker Errors

When a provider experiences repeated failures, the gateway's circuit breaker activates:

| State       | Behavior                                                              |
| :---------- | :-------------------------------------------------------------------- |
| `Closed`    | Normal operation — requests flow through                              |
| `Open`      | Provider failing — requests rejected immediately, next provider tried |
| `Half-Open` | Testing recovery — a few requests allowed through                     |

The circuit breaker opens after 5 consecutive failures and closes after 3 successful requests.

***

## Error Response Structure

All error responses follow this structure:

```typescript theme={null}
interface ErrorResponse {
  error: string;           // Human-readable error message
  type?: string;           // Error category (e.g. "internal_error", "upstream_error")
  code?: string;           // Machine-readable error code
  limit?: number;          // Rate limit maximum (429 only)
  current?: number;        // Current usage (429 only)
  window?: string;         // Time window type (429 only)
  retry_after?: number;    // Seconds to wait (429 only)
  rule_id?: string;        // Rate limit rule ID (429 only)
}
```