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

# Error Handling

> HTTP status codes, error response formats, and conventions across all SNH AI APIs

All SNH AI APIs use conventional HTTP response codes and return structured error information. These conventions apply to every service.

## HTTP Status Codes

| Status Code | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `200`       | Success — request completed successfully                         |
| `206`       | Partial Success — some processing completed, but errors occurred |
| `400`       | Bad Request — invalid parameters or missing required fields      |
| `401`       | Unauthorized — invalid or missing authentication                 |
| `422`       | Validation Error — request validation failed                     |
| `500`       | Internal Server Error — something went wrong on our end          |

## Response Envelope

All successful responses use a standard envelope:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "api_version": "2.0.0",
    "process_time_ms": 1855,
    "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

Include the `correlation_id` when contacting support.

## Error Response Format

All error responses follow a consistent format:

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

For validation errors with multiple issues:

```json theme={null}
{
  "detail": {
    "error": "Validation error",
    "message": "One or more validation errors occurred",
    "errors": {
      "record.search_id": ["search_id is required"],
      "record.candidate_info.date_of_birth": ["date_of_birth must be in YYYY-MM-DD format"]
    }
  }
}
```

## Common Error Scenarios

### Authentication Errors (401)

| Response                                           | Cause                          |
| -------------------------------------------------- | ------------------------------ |
| `"Authentication required. Provide Bearer token."` | Missing `Authorization` header |
| `"Token validation failed: Token has expired"`     | Expired JWT token              |
| `"Invalid API key."`                               | Wrong or revoked API key       |

**Resolution:** Get a new token from `/auth/token`. See [Authentication](/authentication).

### Validation Errors (400, 422)

Validation errors return field-level details so you can fix the request without guessing.

```json theme={null}
{
  "detail": {
    "error": "Validation error",
    "message": "Missing required field: search_id"
  }
}
```

**Resolution:** Fix the request payload. Do not retry — these are not transient errors.

### Partial Success (206)

When a processing stage degrades or fails, the API returns HTTP 206 with partial results:

* `data.status: "partial"`
* `data.errors[]` — error messages from the failed stage
* `data.degradation` — per-stage status
* `data.decision` — whatever decisions could still be produced

```json theme={null}
{
  "success": true,
  "data": {
    "status": "partial",
    "errors": ["Compliance-Engine failed: read timeout after 30s"],
    "decision": { ... },
    "degradation": {
      "xml_transformer": { "status": "available", "error": null },
      "compliance_engine": { "status": "degraded", "error": "read timeout after 30s" }
    }
  }
}
```

### Server Errors (500)

```json theme={null}
{
  "detail": "Internal server error. Please try again later."
}
```

**Resolution:** Retry with exponential backoff. See [Retry Logic](/retry-logic).

For service-specific error scenarios (e.g., cases count mismatch on `/evaluate`), see [Troubleshooting](/troubleshooting).

## Related

* [Retry Logic](/retry-logic) — Retry strategy, timeouts, and code examples
* [Troubleshooting](/troubleshooting) — Service-specific issues and resolution steps
* [API Reference](/api-reference/overview) — Endpoint documentation