Error Codes

Davix H2I returns structured error responses when a public API request cannot be completed. These errors can result from authentication failures, invalid parameters, upload restrictions, rate limits, quota exhaustion, processing timeouts, or endpoint-specific processing failures.

Requests sent to Davix H2I are processed by the platform layer behind the product, including the H2I engine (PixLab) for rendering workflows. When a standard public API request fails, the API returns a structured JSON error response.

Scope #

This page documents the error model for the public API surface:

• POST /v1/h2i
• POST /v1/image
• POST /v1/pdf
• POST /v1/tools

It also includes signed output URL access errors that may occur when opening generated output files returned by the API, such as URLs under:

• /h2i/*
• /image/*
• /pdf/*

These output-access errors are different from normal request-processing errors on /v1/* routes.

Error response format #

Standard public API errors use the following JSON envelope:

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

Field behavior #

• status is always "error"
• top-level code and message are always present
• error.code and error.message are always present
• hint appears only when additional guidance is available
• details appears only when structured diagnostic information is included and safe to expose
• support may appear on some server-side failures
• renewal_url may appear for expired keys when renewal guidance is configured
• request_id is typically included and should be used when tracing a failed request or contacting support

Example error response #

{
  "status": "error",
  "code": "invalid_parameter",
  "message": "The request contains an invalid parameter.",
  "error": {
    "code": "invalid_parameter",
    "message": "The request contains an invalid parameter."
  },
  "request_id": "<REQUEST_ID>"
}

Applications should use the machine-readable code field for programmatic handling.

Public API error codes #

Error Code	HTTP Status	Description	Applies To
invalid_idempotency_key	400	The idempotency header value is invalid	public API requests using idempotency headers
api_key_location_not_allowed	400	In production, the API key was sent in the request body or query instead of a supported header	/v1/*
invalid_parameter	400	The request contains an invalid or unsupported parameter	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
missing_field	400	A required request field is missing	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
dimension_exceeded	400	An uploaded image exceeds the allowed dimension limit	/v1/image, /v1/tools
render_size_exceeded	400	The requested H2I render size exceeds allowed rendering limits	/v1/h2i
invalid_api_key	401	The API key is missing, invalid, or not yet active	/v1/*
key_expired	401	The API key has expired	/v1/*
endpoint_not_allowed	403	The endpoint is not available for the current customer plan	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
unsupported_media_type	415	The uploaded media type is not supported for the request	/v1/image, /v1/pdf, /v1/tools
file_too_large	413	An uploaded file exceeds the per-file size limit	/v1/image, /v1/pdf, /v1/tools
too_many_files	413	Too many files were uploaded in a single request	/v1/image, /v1/pdf, /v1/tools
total_upload_exceeded	413	The total upload size for the request exceeds the allowed limit	/v1/image, /v1/pdf, /v1/tools
invalid_upload	400	The upload could not be validated or processed as a valid input file	/v1/image, /v1/pdf, /v1/tools
html_too_large	413	The HTML payload exceeds the allowed H2I input size limit	/v1/h2i
pdf_page_limit_exceeded	413	The PDF page limit for the selected operation was exceeded	/v1/pdf
rate_limit_exceeded	429	A request rate limit or burst limit was exceeded	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
monthly_quota_exceeded	429	The monthly plan quota has been exhausted	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
rate_limit_store_unavailable	503	The rate-limit backing store was unavailable and the request could not be processed	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
timeout	503	The request exceeded the allowed processing time	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
server_busy	503	The service could not acquire processing capacity for the request	/v1/h2i, /v1/image, /v1/pdf, /v1/tools
html_render_failed	500	HTML rendering failed	/v1/h2i
image_processing_failed	500	Image processing failed	/v1/image
pdf_tool_failed	500	PDF processing failed	/v1/pdf
tool_processing_failed	500	Tool processing failed	/v1/tools
not_found	404	The requested endpoint does not exist	unmatched public routes
internal_error	500	An unexpected internal error occurred	public API fallback error

The external API also uses signed output URL access errors for generated file URLs:

• unauthorized
• invalid_signature
• expired

Validation errors #

Validation errors occur when the request body, parameters, or action-specific values do not meet the endpoint requirements.

Common validation errors include:

• invalid_parameter
• missing_field

For H2I rendering requests, additional validation-related errors include:

• html_too_large
• render_size_exceeded

Example #

{
  "status": "error",
  "code": "invalid_parameter",
  "message": "The provided action is not supported.",
  "error": {
    "code": "invalid_parameter",
    "message": "The provided action is not supported."
  },
  "request_id": "<REQUEST_ID>"
}

Authentication errors #

All external /v1/* routes require API key authentication through one of the supported header formats:

X-Api-Key: <key>

or

Authorization: Bearer <key>

Authentication-related errors include:

• api_key_location_not_allowed
• invalid_api_key
• key_expired

Example #

{
  "status": "error",
  "code": "invalid_api_key",
  "message": "The provided API key is not valid.",
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is not valid."
  },
  "request_id": "<REQUEST_ID>"
}

Upload and media errors #

For upload-based routes such as /v1/image, /v1/pdf, and /v1/tools, the upload and media errors include:

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

These errors do not apply in the same way to /v1/h2i, because /v1/h2i accepts structured request content for HTML rendering rather than multipart file uploads.

Rate limit and quota errors #

The public API enforces request-limiting and quota controls. When those controls are exceeded, the relevant errors include:

• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded

Example #

{
  "status": "error",
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded.",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded."
  },
  "request_id": "<REQUEST_ID>"
}

For exact customer-facing limit values, use the dedicated Rate Limits and Usage Limits pages.

Processing and runtime errors #

Runtime errors occur when the request cannot complete because processing fails, capacity is unavailable, or the request exceeds its allowed processing time.

Runtime errors include:

• timeout
• server_busy
• html_render_failed
• image_processing_failed
• pdf_tool_failed
• tool_processing_failed

Example #

{
  "status": "error",
  "code": "timeout",
  "message": "The request exceeded the allowed processing time.",
  "error": {
    "code": "timeout",
    "message": "The request exceeded the allowed processing time."
  },
  "request_id": "<REQUEST_ID>"
}

Signed output URL errors #

Generated output files may be returned as signed URLs. When accessing those URLs, the documented output-access errors include:

• unauthorized
• invalid_signature
• expired

These errors apply to signed static output access rather than normal request processing on /v1/* routes.

Troubleshooting tips #

• use the code field for application logic
• log the returned request_id for failed requests
• verify that API keys are sent in headers
• validate required fields before sending requests
• keep upload type, file count, file size, and HTML payloads within documented limits
• refer to Rate Limits and Usage Limits for limit values that apply to your plan