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

# Error Responses

> HTTP status codes and error response format for the EntityML Market Data API.

Most application errors return FastAPI-style JSON with a top-level `detail` field:

```json theme={null}
{
  "detail": "Human-readable description of what went wrong"
}
```

Validation errors use a structured `detail` array:

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "date"],
      "msg": "Field required",
      "input": null
    }
  ]
}
```

Usage-limit responses on billable market endpoints add extra fields:

```json theme={null}
{
  "detail": "API usage limit reached. You've used 50/50 calls this month.",
  "error_code": "USAGE_LIMIT_EXCEEDED",
  "current_usage": 50,
  "limit": 50,
  "tier": "free",
  "upgrade_url": "/pricing"
}
```

## Status Codes

| Status Code | Description                                                                            |
| ----------- | -------------------------------------------------------------------------------------- |
| `200`       | Success                                                                                |
| `400`       | Bad Request — missing or invalid parameters                                            |
| `401`       | Unauthorized — invalid or missing API key                                              |
| `404`       | Not Found — resource does not exist                                                    |
| `422`       | Validation Error — required parameters are missing or malformed at the framework level |
| `429`       | Too Many Requests — plan usage limit reached on a billable market endpoint             |
| `500`       | Internal Server Error — something went wrong on our end                                |

## Error Examples

### 401 Unauthorized

Returned when the API key is missing or invalid.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 400 Bad Request

Returned when required parameters are missing or malformed.

```json theme={null}
{
  "detail": "start_timestamp must be less than or equal to end_timestamp"
}
```

### 422 Validation Error

Returned when FastAPI rejects the request before endpoint logic runs.

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "condition_id"],
      "msg": "Field required",
      "input": null
    }
  ]
}
```

### 429 Too Many Requests

Returned when the current plan's monthly market-endpoint allowance has been exhausted.

```json theme={null}
{
  "detail": "API usage limit reached. You've used 50/50 calls this month.",
  "error_code": "USAGE_LIMIT_EXCEEDED",
  "current_usage": 50,
  "limit": 50,
  "tier": "free",
  "upgrade_url": "/pricing"
}
```

### 500 Internal Server Error

Returned when an unexpected server-side error occurs. If this persists, contact [founders@entityml.com](mailto:founders@entityml.com).

```json theme={null}
{
  "detail": "Internal server error: <message>"
}
```