Error Handling

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 (including optional `cases[]` count mismatch on `/evaluate`)
`500`	Internal Server Error — something went wrong on our end

Response Envelope

All successful responses use a standard envelope:

{
  "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:

{
  "detail": "Error message describing what went wrong"
}

For validation errors with multiple issues:

{
  "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
`error.message`: `"Missing X-API-Key header."`	Missing `X-API-Key` on `/auth/token`
`error.message`: `"Invalid API key."`	Wrong or revoked API key on `/auth/token`
`"Authentication required. Provide Bearer token."`	Missing `Authorization` header on `/evaluate`
Token expired / invalid	Expired or tampered JWT on `/evaluate`

/auth/token errors use the envelope {"error":{"code":"UNAUTHORIZED","message":"..."},"timestamp":"..."} (not FastAPI {"detail":"..."}). Resolution: Get a new token from /auth/token. See Authentication.

Validation Errors (400, 422)

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

{
  "detail": {
    "error": "Validation error",
    "message": "Missing required field: search_id"
  }
}

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

Optional `cases[]` count mismatch (422 on `/evaluate`)

Terms first (also in the Glossary):

ID	Meaning
Court search ID (`court_search_id`)	Your identifier for one court search / court grouping in the record (often one county or court result).
Offense ID (`offense_id`)	Your identifier for one charge (offense) inside a case.

record.cases[] is an optional charge map: each row is { court_search_id, offense_id, is_excluded }. Use it when you need to attach your IDs or mark charges excluded. Omit cases or send cases: [] to evaluate every offense — the count gate does not run. When cases[] is non-empty, the distinct court-search-ID count and total offense-ID row count must exactly match the courts and offenses in the parsed XML or record_json. Partial maps are rejected with HTTP 422 and data.status: "validation_required". Trigger: Incomplete cases[] — for example 2 court search IDs and 3 offense rows when the record has 3 courts and 5 offenses. Do not drop excluded charges from the array; include them with is_excluded: true.

{
  "success": false,
  "data": {
    "status": "validation_required",
    "errors": [
      "XML-Transformer failed: XML-Transformer HTTP error 422: Court search ID and offense ID counts do not match the XML: ..."
    ],
    "degradation": {
      "xml_transformer": { "status": "failed", "error": "..." },
      "compliance_engine": { "status": "not_called", "error": null }
    }
  }
}

Do not retry HTTP 422 — fix the payload (complete cases[] or omit it).

See Evaluate → cases[] count reconciliation and Glossary → cases.

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

{
  "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)

{
  "detail": "Internal server error. Please try again later."
}

Resolution: Retry with exponential backoff. See Retry Logic. For additional service-specific issues, see Troubleshooting.

Retry Logic — Retry strategy, timeouts, and code examples
Troubleshooting — Service-specific issues and resolution steps
API Reference — Endpoint documentation

Getting Started

Resources

Error Handling

HTTP Status Codes

Response Envelope

Error Response Format

Common Error Scenarios

Authentication Errors (401)

Validation Errors (400, 422)

Optional `cases[]` count mismatch (422 on `/evaluate`)

Partial Success (206)

Server Errors (500)

​HTTP Status Codes

​Response Envelope

​Error Response Format

​Common Error Scenarios

​Authentication Errors (401)

​Validation Errors (400, 422)

​Optional cases[] count mismatch (422 on /evaluate)

​Partial Success (206)

​Server Errors (500)

​Related

HTTP Status Codes

Response Envelope

Error Response Format

Common Error Scenarios

Authentication Errors (401)

Validation Errors (400, 422)

Optional `cases[]` count mismatch (422 on `/evaluate`)

Partial Success (206)

Server Errors (500)

Related