Common Errors

When integrating with the Davix H2I API, developers may encounter a small set of recurring errors during normal request handling. These usually result from authentication failures, invalid request payloads, upload restrictions, render limits, request throttling, quota exhaustion, or processing constraints.

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.

Standard error structure #

Standard external API errors use this structure:

{
  "status": "error",
  "code": "<string>",
  "message": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "request_id": "<REQUEST_ID>"
}

The full error envelope can also include optional fields such as hint, details, support, and renewal_url, but the fields above are the core response shape used by applications. request_id is typically present, and the platform also exposes Request-Id as a response header.

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

Invalid API key #

Error code
invalid_api_key

HTTP status
401

This error occurs when the API key is missing, invalid, or not yet active for the external /v1/* API.

Common causes #

• the API key is missing from the request
• the API key value is incorrect
• the wrong key was copied into the request
• the key is not valid for the external API surface

Example response #

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

How to fix #

• send the key through X-Api-Key or Authorization: Bearer <key>
• verify the key value carefully
• confirm the key is still active and intended for external API use

Expired API key #

Error code
key_expired

HTTP status
401

This error occurs when the customer API key has expired.

Common causes #

• the key has reached its expiration date
• an older key is being reused after rotation or renewal

How to fix #

• replace the expired key with an active key
• renew or rotate the key through the appropriate customer workflow

API key in the wrong location #

Error code
api_key_location_not_allowed

HTTP status
400

In production, external /v1/* routes reject API keys sent in the request body or query string. Public requests must authenticate through headers.

Common causes #

• sending api_key in the request body
• sending ?key= in the URL
• using a legacy test pattern against a production environment

How to fix #

• move authentication to X-Api-Key or Authorization: Bearer <key>

Missing required fields #

Error code
missing_field

HTTP status
400

This error occurs when a required request field is missing. It is used across /v1/h2i, /v1/image, /v1/pdf, and /v1/tools.

For example, H2I rendering requests require fields such as action and html.

Example response #

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

How to fix #

• verify that all required fields are present
• check the endpoint-specific request body carefully
• for H2I requests, confirm that action and html are included when required

Invalid parameter #

Error code
invalid_parameter

HTTP status
400

This error occurs when a parameter value is malformed, unsupported, or semantically invalid. It is one of the most common validation errors across the public API.

Common causes #

• unsupported action value
• invalid format value
• bad field type
• unsupported parameter combination

Example response #

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

How to fix #

• verify the request against the endpoint reference
• check allowed values for action-specific parameters
• ensure values are sent in the expected types and formats

Endpoint not allowed for plan #

Error code
endpoint_not_allowed

HTTP status
403

This error occurs when the current customer plan does not allow access to the requested endpoint.

How to fix #

• confirm that your plan includes access to the endpoint you are calling
• use an endpoint allowed by your current plan
• upgrade to a plan that includes the required endpoint if needed

HTML content too large #

Error code
html_too_large

HTTP status
413

This error applies to /v1/h2i when the HTML payload exceeds the allowed size limit.

Example response #

{
  "status": "error",
  "code": "html_too_large",
  "message": "HTML content exceeds the allowed maximum size.",
  "error": {
    "code": "html_too_large",
    "message": "HTML content exceeds the allowed maximum size."
  },
  "request_id": "<REQUEST_ID>"
}

How to fix #

• reduce the HTML payload size
• remove unnecessary markup
• simplify oversized inline content

Render size exceeded #

Error code
render_size_exceeded

HTTP status
400

This error applies to /v1/h2i when requested render dimensions exceed the allowed rendering limits.

Example response #

{
  "status": "error",
  "code": "render_size_exceeded",
  "message": "Requested render dimensions exceed size limits.",
  "error": {
    "code": "render_size_exceeded",
    "message": "Requested render dimensions exceed size limits."
  },
  "request_id": "<REQUEST_ID>"
}

How to fix #

• reduce the requested width
• reduce the requested height
• keep render dimensions within the documented H2I limits

Unsupported media type #

Error code
unsupported_media_type

HTTP status
415

This error applies to upload-based routes such as /v1/image, /v1/pdf, and /v1/tools when the uploaded file type is not accepted.

Common causes #

• uploading a file format not supported by the route
• sending the wrong file type for the selected action
• using an unsupported MIME type

How to fix #

• verify that the uploaded file type is supported by the endpoint
• check action-specific media requirements before sending the request

File too large #

Error code
file_too_large

HTTP status
413

This error occurs when an uploaded file exceeds the allowed per-file size limit for /v1/image, /v1/pdf, or /v1/tools.

How to fix #

• reduce the size of the uploaded file
• compress or optimize the file before upload
• split work into multiple requests if appropriate

Total upload exceeded #

Error code
total_upload_exceeded

HTTP status
413

This error occurs when the total size of all uploaded files in a single request exceeds the allowed upload limit.

How to fix #

• reduce the total size of files in the request
• send fewer files in one request
• split work across multiple requests

Too many uploaded files #

Error code
too_many_files

HTTP status
413

This error applies to /v1/image, /v1/pdf, and /v1/tools when the number of uploaded files exceeds the allowed request limit. It does not apply to /v1/h2i, which is the HTML-rendering route.

Example response #

{
  "status": "error",
  "code": "too_many_files",
  "message": "The number of uploaded files exceeds the allowed limit.",
  "error": {
    "code": "too_many_files",
    "message": "The number of uploaded files exceeds the allowed limit."
  },
  "request_id": "<REQUEST_ID>"
}

How to fix #

• reduce the number of uploaded files
• split the work across multiple requests when needed

Invalid upload #

Error code
invalid_upload

HTTP status
400

This error occurs when an uploaded file cannot be validated or processed as a valid input file.

Common causes #

• unreadable or corrupted upload data
• a file that does not match the route’s expected upload handling
• an upload validation failure before processing begins

How to fix #

• verify that the uploaded file is valid and readable
• re-export or regenerate the input file if needed
• resend the request with a clean upload

PDF page limit exceeded #

Error code
pdf_page_limit_exceeded

HTTP status
413

This error applies to /v1/pdf when the selected operation exceeds the allowed page cap for that action.

How to fix #

• reduce the number of pages being processed
• split the PDF operation into smaller jobs
• check the usage limits for the applicable PDF action

Monthly quota exceeded #

Error code
monthly_quota_exceeded

HTTP status
429

This error occurs when a customer key has exhausted its monthly quota.

Example response #

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

How to fix #

• reduce request volume
• move to a plan with an appropriate quota
• wait for quota reset if that matches your billing cycle

Rate limit exceeded #

Error code
rate_limit_exceeded

HTTP status
429

This error occurs when a request rate limit or burst limit is exceeded on the external /v1/* API.

Example response #

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

How to fix #

• slow request frequency
• reduce avoidable bursts
• pace automated traffic more evenly
• review the Rate Limits page for the limits that apply to your plan

Server busy #

Error code
server_busy

HTTP status
503

This error occurs when the service cannot accept the request because processing capacity is temporarily unavailable.

Example response #

{
  "status": "error",
  "code": "server_busy",
  "message": "The service is temporarily busy.",
  "error": {
    "code": "server_busy",
    "message": "The service is temporarily busy."
  },
  "request_id": "<REQUEST_ID>"
}

How to fix #

• avoid large bursts of simultaneous requests
• queue or pace requests
• retry carefully only when the failure is temporary

Timeout #

Error code
timeout

HTTP status
503

This error occurs when the request exceeds the allowed processing time.

Example response #

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

How to fix #

• simplify the request
• reduce render or processing complexity where possible
• retry cautiously only when the failure appears temporary

Request ID for debugging #

Standard API errors almost always include request_id, and the platform also exposes Request-Id as a response header. Applications should log that value whenever a request fails so individual failures can be traced more easily.

How to use this page #

Use this page for the most likely customer-facing failures during normal integration work. For the complete canonical list of public error codes, use Error Codes. For exact request and plan limits, use Rate Limits and Usage Limits.