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
`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
`"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.

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.

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 service-specific error scenarios (e.g., cases count mismatch on /evaluate), see Troubleshooting.

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

​HTTP Status Codes

​Response Envelope

​Error Response Format

​Common Error Scenarios

​Authentication Errors (401)

​Validation Errors (400, 422)

​Partial Success (206)

​Server Errors (500)

​Related