Error responses

Ovok's standard HTTP API errors use the RFC 9457 Problem Details media type, application/problem+json. The response keeps the legacy fields used by existing clients while exposing a stable problem type, the HTTP status, a request path, a trace ID, and structured field errors.

Response bodyCopy Anchor Link

{
  "type": "https://docs.ovok.com/errors/validation-failed",
  "status": 422,
  "detail": "The request has invalid fields.",
  "instance": "/v1/slim/patient",
  "traceId": "01JQEXAMPLE8D2A4B6C",
  "errors": [
    { "field": "email", "code": "FIELD_INVALID_EMAIL", "params": null }
  ],
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "timestamp": "2026-10-22T00:00:00.000Z",
  "path": "/v1/slim/patient",
  "message": ["email must be an email"],
  "requestId": "request-id"
}

type is a stable URI for the error category. Its slug normally comes from the HTTP status mapping below; an endpoint may use a specific machine code instead. Use status for HTTP handling and type for category-specific handling. detail is human-readable and may be null; do not parse it for program logic. instance is the request path without its query string.

traceId identifies the request in Ovok's tracing and logs. It may be null when no trace context is available. Include it when reporting an error to support. The legacy requestId, statusCode, error, timestamp, path, and message fields are retained for existing clients during migration.

Field errorsCopy Anchor Link

errors is always an array in this response format. A field-level error contains:

Correct the fields named by errors before retrying. The API limits the response to 100 field errors. These nested errors[].code values are field codes; they are separate from the top-level problem type.

Stable status typesCopy Anchor Link

When no endpoint-specific machine code is supplied, the problem type is https://docs.ovok.com/errors/<slug>. The pages below document the types mapped by the current Ovok core release.

An endpoint can supply a stable machine code that replaces the status-derived type. The endpoint-specific machine-code registry lists all 64 types emitted by the audited core release, with one troubleshooting page per type. It was checked against merged ovok-core development commit 9a6ca1c2523079bcb8f7d4cbee583681c475d683; update the registry and pages when a backend change adds or removes a type. Published HTTP endpoint error sections link their status values to the generic guidance and each listed machine code to its canonical page. Some backend operations have no dedicated public route page yet; their machine-code page remains the reference and links to the closest available guide where one exists.

Protocol-specific errorsCopy Anchor Link

Not every Ovok API uses Problem Details. FHIR routes return a FHIR OperationOutcome; interpret its issue entries and expressions using the FHIR format. OAuth token endpoints and the MCP authorization flow keep their protocol-specific error members; the account refresh route documents its own status outcomes. MCP authentication, JSON-RPC, and tool-call failures keep their distinct response bodies; see MCP server troubleshooting and MCP tools. GraphQL requests use the GraphQL errors response envelope; see the GraphQL API guide. Do not parse these protocol responses as Problem Details.

Top-level codeCopy Anchor Link

Ovok does not currently add a top-level code member to Problem Details. The FhirStore client interprets a string top-level code as the complete error and can lose the rest of the response body. Use type, status, and the documented field errors instead. The nested errors[].code remains available for validation.