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.

404 Not Found

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

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.

403 Restricted vocabulary

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

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);
  }
}

API Reference

Search

Concepts

Concept Hierarchy

Mappings

FHIR Resolver

Relationships

Domains & Classifications

Vocabularies

API error codes

Error handling

Envelope fields

HTTP status codes

Authentication and authorization

Request validation and safety

Resources, vocabularies, and mappings

Licence-restricted vocabularies

Vocabulary releases

Limits and business rules

Search and operational errors

Administrative endpoint errors

Client handling

​Error handling

​Envelope fields

​HTTP status codes

​Authentication and authorization

​Request validation and safety

​Resources, vocabularies, and mappings

​Licence-restricted vocabularies

​Vocabulary releases

​Limits and business rules

​Search and operational errors

​Administrative endpoint errors

​Client handling

Error handling

Envelope fields

HTTP status codes

Authentication and authorization

Request validation and safety

Resources, vocabularies, and mappings

Licence-restricted vocabularies

Vocabulary releases

Limits and business rules

Search and operational errors

Administrative endpoint errors

Client handling