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

# API error codes

> The OMOPHub REST error envelope, canonical error codes, HTTP statuses, and recovery guidance.

# Error handling

REST endpoints return JSON errors in a consistent envelope. Branch first on the
HTTP status, then on `error.code` when your integration needs a more specific
recovery path.

```json 404 Not Found theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Concept with identifier '73211009' not found",
    "details": {
      "resource": "Concept",
      "identifier": 73211009
    }
  },
  "meta": {
    "request_id": "f164f3e4-a1d6-4b20-9b8e-e009074cb925",
    "timestamp": "2026-09-12T22:44:24.493Z"
  }
}
```

## Envelope fields

| Field | Type | Required | Description |
| - | - | - | - |
| `success` | boolean | Yes | Always `false` for an error response. |
| `error.code` | string | Yes | Stable, machine-readable code in lowercase `snake_case`. |
| `error.message` | string | Yes | Human-readable explanation. Do not branch on this text. |
| `error.details` | object or array | No | Structured context such as invalid fields, available releases, or a restricted vocabulary ID. |
| `error.remediation` | string\[] | No | Suggested recovery steps for selected operational errors. |
| `meta.request_id` | string | Yes | Correlation ID to include in support requests. |
| `meta.timestamp` | string | Yes | ISO 8601 time at which the response was produced. |

> [!NOTE]
>
> Nested codes such as `error.details.validationErrors[].code` describe an
> individual validator rule and are not part of the top-level error-code
> contract. FHIR endpoints return a FHIR `OperationOutcome`; its `issue[].code`
> values follow the FHIR code system rather than this REST convention.

## HTTP status codes

| HTTP status | Meaning |
| - | - |
| `400 Bad Request` | The request is malformed or fails validation. |
| `401 Unauthorized` | Credentials are missing, invalid, expired, or no longer active. |
| `403 Forbidden` | Credentials are valid, but the operation or vocabulary is not permitted. |
| `404 Not Found` | A resource, vocabulary release, endpoint, or mapping does not exist. |
| `405 Method Not Allowed` | The path exists but does not support the HTTP method. |
| `409 Conflict` | The request conflicts with existing state. |
| `410 Gone` | The requested vocabulary release is archived. |
| `412 Precondition Failed` | A required precondition is not satisfied. |
| `413 Payload Too Large` | The request body exceeds the configured limit. |
| `422 Unprocessable Entity` | Domain or healthcare data is structurally valid but cannot be processed. |
| `429 Too Many Requests` | A burst, daily, monthly, or other quota has been exceeded. |
| `500 Internal Server Error` | An unexpected application, database, or cache failure occurred. |
| `502 Bad Gateway` | An upstream service returned an invalid or failed response. |
| `503 Service Unavailable` | A required service is unavailable. |
| `504 Gateway Timeout` | The operation exceeded its execution deadline. |

`validation_error` uses **400**, and `invalid_api_key` uses **401**. These are
the runtime contract; older documentation that listed 422 and 403 respectively
was incorrect.

JSON (including FHIR JSON) and URL-encoded request bodies are limited to **256
KiB (262,144 bytes)**. The limit is enforced while the body is read and before
JSON deserialization. REST requests over the limit return `413
payload_too_large`; FHIR routes represent the same status as an
`OperationOutcome`.

## Authentication and authorization

| Code | HTTP | Meaning |
| - | - | - |
| `missing_api_key` | 401 | No API key was supplied. |
| `invalid_api_key` | 401 | The API key is malformed, expired, revoked, or unknown. |
| `invalid_credentials` | 401 | Supplied credentials could not be authenticated. |
| `unauthorized` | 401 | Authentication is required or invalid. |
| `authentication_error` | 401 | Authentication processing failed. |
| `missing_session` | 401 | A required session is absent. |
| `invalid_session` | 401 | The supplied session is invalid or expired. |
| `session_validation_error` | 500 | Session validation could not be completed. |
| `token_expired` | 401 | The authentication token has expired. |
| `token_invalid` | 401 | The authentication token is invalid. |
| `account_locked` | 403 | The account is locked. |
| `account_suspended` | 403 | The account is suspended. |
| `forbidden` | 403 | The authenticated caller cannot perform the operation. |
| `insufficient_permissions` | 403 | The API key lacks a required permission. |
| `authorization_error` | 403 | Authorization processing failed. |

## Request validation and safety

| Code | HTTP | Meaning |
| - | - | - |
| `validation_error` | 400 | One or more request fields failed validation. |
| `bad_request` | 400 | The request is malformed, including invalid JSON. |
| `invalid_input` | 400 | Input is not valid for the operation. |
| `invalid_format` | 400 | A value has an invalid format. |
| `value_out_of_range` | 400 | A numeric or date value is outside its allowed range. |
| `missing_required_field` | 400 | A required field is absent. |
| `missing_path_parameters` | 400 | Required URL path parameters are absent. |
| `payload_too_large` | 413 | The request body is larger than the configured limit. |
| `batch_size_exceeded` | 400 | A batch contains too many entries. |
| `search_complexity_exceeded` | 400 | A search exceeds the caller's complexity limit. |
| `sanitization_error` | 400 | Input sanitization failed. |
| `phi_detected` | 400 | Input was rejected because it may contain protected health information. |
| `cors_not_allowed` | 403 | The request origin is not allowed by CORS policy. |
| `method_not_allowed` | 405 | The endpoint does not support the HTTP method. |

## Resources, vocabularies, and mappings

| Code | HTTP | Meaning |
| - | - | - |
| `not_found` | 404 | The requested resource does not exist. |
| `concept_not_found` | 404 | The requested OMOP concept does not exist. |
| `vocabulary_not_found` | 404 | The requested vocabulary does not exist. |
| `mapping_not_found` | 404 | No requested mapping exists. |
| `api_key_not_found` | 404 | The API key does not exist or was already revoked. |
| `endpoint_not_found` | 404 | A known incorrect endpoint was requested; inspect `error.suggestion` for the canonical path. |
| `resource_already_exists` | 409 | A resource with the same identifier already exists. |
| `resource_unavailable` | 404 or 503 | The resource exists but is not currently available. |
| `resource_locked` | 409 | The resource cannot be changed while locked. |
| `invalid_concept_code` | 400 | The concept code is invalid for the requested vocabulary. |
| `invalid_mapping` | 400 | Mapping input is invalid. |

### Licence-restricted vocabularies

`vocabulary_restricted` (403) means the caller has not been authorized for the
requested licensed vocabulary. The current policy is:

| Vocabulary | Access policy |
| - | - |
| CPT4 | Available after annual UMLS validation in the Dashboard; expires each January 30. |
| GPI | Unavailable to every caller. |
| MedDRA | Unavailable to every caller. |

```json 403 Restricted vocabulary theme={null}
{
  "success": false,
  "error": {
    "code": "vocabulary_restricted",
    "message": "CPT4 requires annual UMLS validation in the OMOPHub Dashboard.",
    "details": { "vocabulary_id": "CPT4" }
  },
  "meta": {
    "request_id": "609eab47-a1d6-4b20-9b8e-e009074cb925",
    "timestamp": "2026-09-12T22:44:24.493Z"
  }
}
```

A successful CPT4 validation applies to all API keys owned by that Dashboard
user. It never applies across users. OMOPHub does not retain the submitted UMLS
key. See [CPT4 access](https://docs.omophub.com/guides/production/cpt4-access.md) for setup and licensing
details.

## Vocabulary releases

| Code | HTTP | Meaning |
| - | - | - |
| `version_not_found` | 404 | The requested `vocab_release` does not exist. `error.details.available_versions` lists valid releases. |
| `version_archived` | 410 | The requested release has been archived. |
| `version_routing_error` | 500 | The API could not resolve the requested release. |

`version_not_found` replaces the legacy, documentation-only
`version_not_supported` code. Unknown vocabulary releases have resource-not-found
semantics and return 404.

## Limits and business rules

| Code | HTTP | Meaning |
| - | - | - |
| `rate_limit_exceeded` | 429 | The short-window request rate was exceeded. Honor `Retry-After`. |
| `daily_quota_exceeded` | 429 | The daily request quota was exceeded. |
| `monthly_limit_exceeded` | 429 | The monthly subscription limit was exceeded. |
| `quota_exceeded` | 429 | Another configured quota was exceeded. |
| `business_rule_violation` | 400 or 409 | The operation violates a business rule. |
| `invalid_operation` | 400 | The requested operation is invalid. |
| `operation_not_allowed` | 403 or 409 | The operation is not allowed in the current context. |
| `precondition_failed` | 412 | A required precondition is not satisfied. |
| `conflict` | 409 | The request conflicts with current state. |
| `conflict_error` | 409 | Conflict handling failed. |

## Search and operational errors

| Code | HTTP | Meaning |
| - | - | - |
| `search_error` | 500 | A search operation failed. |
| `search_failed` | 500 | A search could not be completed. |
| `semantic_search_error` | 500 | Semantic search failed. |
| `service_unavailable` | 503 | A required service is unavailable. |
| `external_service_error` | 502 or 503 | An upstream service failed. |
| `timeout` | 504 | The operation exceeded its deadline. |
| `timeout_error` | 504 | Timeout handling reported a failure. |
| `circuit_breaker_open` | 503 | Requests are temporarily blocked after repeated dependency failures. |
| `database_error` | 500 | A database operation failed. |
| `cache_error` | 500 | A cache operation failed. |
| `application_error` | 500 | The application could not complete the operation. |
| `internal_server_error` | 500 | An unexpected server error occurred. |
| `internal_error` | 500 | A legacy internal component reported an unexpected error. |
| `health_check_failed` | 503 | One or more health-check components failed. |
| `healthcare_data_error` | 422 | Healthcare data could not be processed. |
| `security_error` | 403 or 500 | A security control failed or rejected the request. |
| `compliance_violation` | 403 | A compliance policy rejected the operation. |
| `audit_failure` | 500 | Required audit recording failed. |
| `data_integrity_error` | 422 or 500 | Data failed an integrity check. |

## Administrative endpoint errors

These codes are returned by authenticated API-key management and performance
diagnostic endpoints.

| Code | HTTP | Meaning |
| - | - | - |
| `api_key_creation_failed` | 500 | API-key creation returned no result. |
| `api_key_creation_error` | 500 | API-key creation raised an error. |
| `api_key_list_error` | 500 | API keys could not be listed. |
| `api_key_revocation_error` | 500 | API-key revocation failed. |
| `missing_sql_query` | 400 | A diagnostic request omitted its SQL query. |
| `invalid_query_type` | 400 | A diagnostic request attempted a non-SELECT query. |
| `performance_analysis_error` | 500 | Query-plan analysis failed. |
| `quick_check_error` | 500 | A quick performance check failed. |
| `status_error` | 500 | Performance status could not be read. |

## Client handling

```typescript theme={null}
const response = await fetch(url, options);
const body = await response.json();

if (!response.ok) {
  if (body.error.code === 'rate_limit_exceeded') {
    await wait(Number(response.headers.get('retry-after') ?? 60) * 1000);
  } else if (body.error.code === 'version_not_found') {
    console.error(body.error.details?.available_versions);
  } else {
    console.error(body.meta.request_id, body.error.message);
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.