Handling API Errors

Overview #

When integrating with Davix H2I, applications should be prepared to handle API errors in a structured way. The external API returns standardized JSON error responses for standard API failure paths, allowing applications to identify what went wrong and respond appropriately. This helps keep integrations stable when requests fail because of validation issues, authentication problems, usage limits, or rendering failures.

Requests sent through the external API are processed by the H2I engine (PixLab) behind the Davix H2I product layer. When request processing fails on a standard external API path, the API uses a shared error-response model to describe the failure.

Standard API error structure #

Davix H2I uses a consistent JSON error envelope for standard API errors generated through the shared sendError(...) path. The canonical structure is:

{
  "status": "error",
  "code": "<string>",
  "message": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "hint": "<optional string>",
    "details": "<optional sanitized value>",
    "support": {
      "email": "<optional>",
      "url": "<optional>",
      "website": "<optional>"
    },
    "renewal_url": "<optional string>"
  },
  "request_id": "<optional string>"
}

The loaded docs state that top-level status, code, message, and nested error.code, error.message are always present in this standard envelope. hint, details, support, and renewal_url are conditional fields. request_id is injected when request correlation is available.

Example error response:

{
  "status": "error",
  "code": "missing_field",
  "message": "Missing required field",
  "error": {
    "code": "missing_field",
    "message": "Missing required field"
  },
  "request_id": "<REQUEST_ID>"
}

Applications should inspect the machine-readable code field first and treat the human-readable message as descriptive context.

Fields commonly present in an error response #

Field	Description
status	Indicates the request failed
code	Machine-readable error code
message	Human-readable error description
error	Nested error object with canonical error data
request_id	Request correlation identifier when present

The external error architecture also notes that Request-Id is mirrored as a response header, and standard error payloads almost always include request_id because request-id middleware runs very early in the request lifecycle.

Common categories of API errors #

Authentication errors #

Authentication errors occur when the API key is missing, invalid, expired, or supplied in a disallowed location.

Documented examples include:

• invalid_api_key
• key_expired
• api_key_location_not_allowed

External /v1/* routes accept authentication through:

• X-Api-Key: <key>
• Authorization: Bearer <key>

In non-production environments, body/query key transport is accepted. In production, those locations are explicitly rejected.

Request validation errors #

Validation errors occur when required fields are missing or parameter values are invalid.

Documented examples include:

• missing_field
• invalid_parameter

These are used across the public external routes for request-shape and parameter-validation failures.

Rendering and processing errors #

Processing errors occur when request execution fails after validation.

Relevant documented examples include:

• html_too_large
• render_size_exceeded
• html_render_failed
• image_processing_failed
• pdf_tool_failed
• tool_processing_failed

The broader error architecture also documents runtime failures such as timeout and server_busy when execution is interrupted by time or capacity constraints.

Rate limiting and quota errors #

These errors occur when usage controls are exceeded.

Documented examples include:

• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded

The loaded limits docs show:

• public traffic is subject to daily per-endpoint controls
• customer traffic can also be subject to burst limiting
• customer keys use monthly quota reservation/finalization flows

Because you want plan and limit values centralized elsewhere, this page should explain the error types without repeating numeric quota tables.

Processing capacity errors #

Capacity-related errors occur when the backend cannot process the request within current execution constraints.

Documented examples include:

• server_busy
• timeout

The docs tie server_busy to semaphore or concurrency-slot exhaustion and timeout to timeout middleware or route-level abort handling.

Using request identifiers for debugging #

The platform creates a request UUID very early in the lifecycle and mirrors it as the Request-Id response header. Standard JSON error responses also include request_id when request correlation is attached to the payload. This allows failed requests to be traced more easily during debugging.

Applications should log the request identifier whenever an error occurs.

Example:

Request failed — request_id=<REQUEST_ID>

That identifier is the primary correlation token for investigating a specific failed request.

Using idempotency keys #

Davix H2I supports optional idempotency headers:

• Idempotency-Key
• X-Idempotency-Key

The global middleware validates these headers early in the request lifecycle. Invalid values fail with invalid_idempotency_key, and valid keys are echoed back through the Idempotency-Key response header.

Idempotency keys are useful for request correlation and safer retry workflows. The loaded documentation does not establish a universal guarantee that every repeated request with the same idempotency key will always return a previously generated response body, so public documentation should not promise replay behavior beyond what is explicitly documented. That caution is an inference from the absence of such a guarantee in the loaded docs.

Retry strategies #

Some errors are more likely to be temporary than others. Based on the documented error model, retry consideration is most relevant for transient conditions such as:

• server_busy
• timeout
• some cases of rate_limit_exceeded

By contrast, validation errors such as missing_field or invalid_parameter, and authentication errors such as invalid_api_key, should generally be treated as request-correction issues rather than retry candidates. This distinction follows directly from the documented meanings of those error codes.

Because the loaded docs do not define an official retry schedule, public documentation should recommend cautious retry logic without prescribing unsourced exact intervals.

Global fallback errors #

In addition to route-specific errors, the global error model defines:

• not_found for unmatched routes
• internal_error for unhandled exceptions normalized by the final error middleware

These are part of the standard fallback behavior for the external API surface.

Important scope note #

The standardized JSON error envelope described above applies to standard API error paths. The loaded docs also describe some non-standard response shapes elsewhere in the system, such as /health degraded responses and certain admin HTML or plain-text failures. For public customer-facing documentation, this page should focus on the external API error model used for /v1/* routes.

Best practices for error handling #

• Validate request data before sending it, especially required fields and action-specific parameters.
• Inspect the machine-readable code field first.
• Log the full error payload when appropriate, including request_id.
• Treat authentication and validation errors as request-correction issues.
• Treat capacity and timeout failures as potentially temporary conditions.
• Monitor usage patterns to reduce avoidable limit and quota failures.

These practices are consistent with the documented external API error model and its distinction between validation, authentication, rate-limit, quota, and processing/runtime failures.