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

# Errors

> Error response format, codes, and HTTP status mapping.

All API errors return a consistent JSON envelope.

## Error shape

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Validation failed.",
    "errors": []
  }
}
```

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| `error.type`    | string | Error category                            |
| `error.code`    | string | Machine-readable code (optional)          |
| `error.message` | string | Human-readable description                |
| `error.errors`  | array  | Field-level validation details (optional) |

## Error codes

| Code                      | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `invalid_credentials`     | Wrong `client_id` or `client_secret`                  |
| `insufficient_scope`      | Token lacks required permission                       |
| `api_key_disabled`        | API credential has been disabled                      |
| `auth_rate_limited`       | Too many failed auth attempts                         |
| `rate_limited`            | API request rate limit exceeded                       |
| `validation_failed`       | Request body or query validation failed               |
| `idempotency_in_progress` | Duplicate idempotency key while request is processing |
| `version_mismatch`        | API version conflict (reserved for future use)        |

## HTTP status mapping

| Status | When                                                             |
| ------ | ---------------------------------------------------------------- |
| `400`  | Invalid JSON, validation errors, unsupported API version at auth |
| `401`  | Missing or invalid bearer token, invalid credentials at auth     |
| `403`  | Insufficient scope, disabled API credential                      |
| `404`  | Resource not found                                               |
| `409`  | Idempotency conflict (request in progress)                       |
| `429`  | Rate limit exceeded                                              |
| `500`  | Internal server error                                            |

## Validation errors

When request validation fails, the `errors` array contains Zod-style field details:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Validation failed.",
    "errors": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "array",
        "inclusive": true,
        "exact": false,
        "message": "At least one scope is required",
        "path": ["scopes"]
      }
    ]
  }
}
```

## Response headers on errors

Error responses still include `ST-Api-Version` when the API version is known from the token or auth flow.