Error Model

When interacting with the Davix H2I API, a request can fail because of authentication issues, invalid input, unsupported files, request limits, quota exhaustion, or processing failures. In those cases, the API returns a structured error response instead of a success response.

For the public API, the error model is designed to give applications a consistent machine-readable code, a human-readable message, and a request identifier that can be used for debugging and support. Errors can occur before the request reaches the H2I engine (PixLab) or during processing.

Standard Error Response Structure #

Standard public API errors use a structured JSON envelope.

{
  "status": "error",
  "code": "<ERROR_CODE>",
  "message": "<HUMAN_READABLE_MESSAGE>",
  "error": {
    "code": "<ERROR_CODE>",
    "message": "<HUMAN_READABLE_MESSAGE>",
    "hint": "<OPTIONAL_HINT>",
    "details": "<OPTIONAL_DETAILS>"
  },
  "request_id": "<REQUEST_ID>"
}

The loaded error architecture confirms the standard JSON error envelope includes:

• status
• top-level code
• top-level message
• nested error.code
• nested error.message
• optional error.hint
• optional error.details
• optional support metadata for some server-side failures
• request_id

request_id is attached by the request pipeline and is also mirrored in the Request-Id response header.

Error Response Fields #

status #

Always "error" for standard API error responses.

code #

A machine-readable top-level error code. This is useful for programmatic handling.

message #

A human-readable explanation of the error.

error.code #

The machine-readable error code repeated inside the nested error object.

error.message #

The human-readable message repeated inside the nested error object.

error.hint #

An optional hint that may help explain how to correct the problem. This is only present when the route provides one.

error.details #

Optional structured details. These are sanitized before being returned.

request_id #

A unique request identifier used for debugging, tracing, and support. The platform generates this very early in the request pipeline and injects it into JSON error responses.

HTTP Status Codes #

Public API error responses use standard HTTP status codes. The loaded error documentation confirms these common public statuses:

HTTP Status	Meaning
400	Invalid request, missing field, invalid parameter, invalid idempotency key, invalid API key location
401	Authentication failed or key expired
403	Access denied for the authenticated plan or signed URL auth failure in some contexts
404	Endpoint not found
413	File too large, too many files, total upload too large, or page/HTML size limits in some routes
415	Unsupported media type
429	Rate limit exceeded or monthly quota exceeded
500	Internal processing failure or uncaught server error
503	Timeout, server busy, or rate-limit store unavailable

These statuses are used across the public /v1/* API and related signed output access behavior.

Common Public Error Categories #

Authentication Errors #

These occur when the request cannot be authenticated correctly.

Common public auth-related codes include:

• invalid_api_key
• key_expired
• api_key_location_not_allowed

These apply to the public /v1/* routes.

Validation Errors #

These occur when required input is missing or invalid.

Common codes include:

• missing_field
• invalid_parameter
• invalid_idempotency_key

These are used when required request fields are absent, parameters are malformed, or request metadata is invalid.

Upload and Media Errors #

These occur when uploaded content violates route constraints.

Common codes include:

• file_too_large
• too_many_files
• total_upload_exceeded
• dimension_exceeded
• invalid_upload
• unsupported_media_type

These are used on upload-based public endpoints such as /v1/image, /v1/pdf, and /v1/tools.

Rate Limit Errors #

These occur when request frequency exceeds the allowed rate.

Common code:

• rate_limit_exceeded

A related operational error can also occur:

• rate_limit_store_unavailable

For public customer-facing docs, rate_limit_exceeded is the primary rate-limit error customers need to handle.

Usage Quota Errors #

These occur when the account or plan has no remaining monthly quota for the current period.

Common code:

• monthly_quota_exceeded

This is returned with HTTP 429.

Processing and Runtime Errors #

These occur after the request passes initial validation but processing cannot complete successfully.

Common codes include:

• timeout
• server_busy
• html_render_failed
• image_processing_failed
• pdf_tool_failed
• snapshot_failed

These errors represent runtime or processing failures in the route pipeline or H2I engine (PixLab).

Limit Errors #

Some endpoint-specific size or content limits return dedicated error codes, such as:

• html_too_large
• render_size_exceeded
• pdf_page_limit_exceeded

These indicate that the request exceeded a supported route limit. Customer-facing numeric values for those limits should be documented only in the dedicated Errors and Limits section.

Signed URL Access Errors #

When accessing signed output URLs, the platform can return errors such as:

• unauthorized
• invalid_signature
• expired

These apply to signed static output access such as /h2i/*, /image/*, and /pdf/*, and optionally /tools/* when signed output is enabled.

Example Error Responses #

Authentication Error #

{
  "status": "error",
  "code": "invalid_api_key",
  "message": "Invalid API key.",
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key."
  },
  "request_id": "<REQUEST_ID>"
}

Missing Field Error #

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

Quota Error #

{
  "status": "error",
  "code": "monthly_quota_exceeded",
  "message": "Monthly quota exceeded.",
  "error": {
    "code": "monthly_quota_exceeded",
    "message": "Monthly quota exceeded."
  },
  "request_id": "<REQUEST_ID>"
}

These examples reflect the verified standard error envelope used by the public API.

Retryable vs Non-Retryable Errors #

Applications should not treat every error the same way.

Often Retryable #

These may succeed later if retried appropriately:

• rate_limit_exceeded
• timeout
• server_busy
• some 500 and 503 failures

Usually Not Retryable Without Changes #

These should usually be corrected before retrying:

• invalid_api_key
• key_expired
• missing_field
• invalid_parameter
• unsupported_media_type
• file_too_large
• monthly_quota_exceeded

This distinction helps applications choose between backoff-and-retry behavior and request correction.

Debugging Errors #

When debugging a failed request:

• inspect the HTTP status code
• inspect the error code
• read the message
• check error.hint or error.details if present
• record the request_id
• verify authentication, parameters, files, and endpoint-specific requirements

request_id is especially important for support and tracing because it is attached consistently to standard JSON error responses.

Where Errors Can Occur #

Errors can occur at different points in the request lifecycle.

Before Processing #

Examples:

• authentication failures
• invalid idempotency key
• missing required fields
• unsupported media type
• upload limit failures
• rate-limit and quota rejections

During Processing #

Examples:

• HTML render failure
• image processing failure
• PDF processing failure
• timeout
• server busy conditions

This distinction is useful when deciding whether to fix the request, retry later, or escalate the failure.

Important Scope Note #

For customer-facing documentation, this page describes the standard public API error model used by the public /v1/* endpoints and related signed output access.

Some other routes in the system, such as /health, can use non-standard response shapes in specific situations. Internal and admin routes also have their own behaviors and are not part of the customer-facing public API model described here.

Summary #

The Davix H2I public API uses a structured error model to return consistent information when a request fails.

Standard public errors include a JSON envelope with status, code, message, nested error information, and request_id. Public routes use standard HTTP status codes and machine-readable error codes such as invalid_api_key, missing_field, invalid_parameter, rate_limit_exceeded, monthly_quota_exceeded, unsupported_media_type, timeout, and route-specific processing failures. By handling these responses correctly, applications can integrate with the H2I engine (PixLab) more reliably and recover from failures more effectively.