Debugging API Requests

When integrating with the Davix H2I API, requests may fail because of authentication problems, invalid request payloads, render limits, upload restrictions, rate limits, quota exhaustion, signed output URL problems, or runtime 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 external API request fails, the API returns a structured JSON error response that can be used to identify the failure point.

Step 1 — Inspect the error response #

Every standard failed API request returns a structured JSON 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>"
}

The most important debugging fields are:

Field	Purpose
status	Indicates the request failed
code	Machine-readable error code
message	Human-readable description
error.code	Nested canonical error code
error.message	Nested canonical error message
request_id	Request correlation identifier

Applications should log the full error response when possible, especially the machine-readable code and request_id. Standard JSON error payloads usually include request_id, and the same ID is also exposed in the Request-Id response header.

Step 2 — Verify authentication #

One of the most common causes of failed requests is incorrect authentication.

External /v1/* routes accept authentication through:

X-Api-Key: <H2I_API_KEY>

or

Authorization: Bearer <H2I_API_KEY>

Common authentication-related errors include:

• invalid_api_key
• key_expired
• api_key_location_not_allowed

To debug authentication issues:

• verify the API key value carefully
• confirm the header name is correct
• ensure the key is sent in headers, not in the body or query string in production
• confirm the key has not expired

Step 3 — Validate the request payload #

The public API validates request payloads before processing completes. Invalid or malformed input can produce validation errors such as:

• missing_field
• invalid_parameter

Common payload problems include:

• missing required fields
• unsupported parameter values
• malformed JSON
• wrong field names
• wrong parameter types

For example, /v1/h2i requires action and html, with additional supported fields depending on the selected action.

Example request body:

{
  "action": "image",
  "html": "<div>Hello</div>",
  "width": 1200,
  "height": 630
}

To debug payload problems:

• confirm required fields are present
• check parameter names carefully
• validate JSON structure
• compare the request against the endpoint reference

Step 4 — Check H2I render limits #

The /v1/h2i route enforces H2I-specific request limits. Common H2I limit-related errors include:

• html_too_large
• render_size_exceeded

To debug H2I limit failures:

• reduce the HTML payload size
• reduce requested output dimensions
• simplify overly large or complex layouts
• compare the request against the Usage Limits page for the limits that apply to your plan

Step 5 — Verify upload and media limits #

For upload-based routes such as /v1/image, /v1/pdf, and /v1/tools, the platform enforces upload and media validation rules. Common upload-related errors include:

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

These errors do not apply in the same way to /v1/h2i, because /v1/h2i is the HTML-rendering route rather than the multipart upload route.

To debug upload issues:

• reduce file size
• upload fewer files in a single request
• confirm that the uploaded file type is supported by the endpoint
• verify that the uploaded file is valid and readable
• split large operations into multiple requests where appropriate

Step 6 — Check rate limits and quotas #

External /v1/* routes enforce request-limiting and quota controls. Relevant errors include:

• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded

To debug these failures:

• slow request frequency
• reduce avoidable bursts
• confirm that the current plan has not exhausted its monthly quota
• inspect repeated failures together with request timestamps and request_id
• compare the behavior against the Rate Limits and Usage Limits pages

Step 7 — Handle concurrency and timeout failures #

The platform can reject requests when processing capacity is unavailable or when a request takes too long to complete. Relevant runtime errors include:

• server_busy
• timeout

server_busy indicates that the service could not accept the request because processing capacity was temporarily unavailable.
timeout indicates that the request exceeded the allowed processing time.

To debug these failures:

• look for bursts of simultaneous requests
• reduce request complexity where possible
• treat these errors as potentially temporary
• retry cautiously only when the failure appears transient

Step 8 — Check the returned output URL #

Some integrations succeed at the API request level but fail later when opening the returned file URL. Generated output URLs are signed, and signed output access can fail with:

• unauthorized
• invalid_signature
• expired

To debug signed output URL issues:

• verify that the full returned URL is being used
• confirm that required query parameters are still present
• avoid modifying signed URLs
• regenerate the file URL by rerunning the request if the link has expired

Step 9 — Reproduce the request with cURL #

Testing with cURL is often the fastest way to isolate whether a failure comes from application code or from the request itself.

Endpoint:

POST https://pixlab.davix.dev/v1/h2i

Minimal reproducible H2I image request:

curl -sS -X POST "https://pixlab.davix.dev/v1/h2i" \
  -H "X-Api-Key: <H2I_API_KEY>" \
  -H "Idempotency-Key: debug-h2i-image-001" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "image",
    "html": "<div>Hello World</div>",
    "css": "body{margin:0}",
    "width": 800,
    "height": 600,
    "format": "png"
  }'

This is a valid debugging request for the /v1/h2i image flow. It is useful for isolating request construction problems, but it is not the complete parameter reference for the endpoint. Use the endpoint reference page for the full supported request surface.

Debugging checklist #

When troubleshooting API issues, check the following:

• API key is valid and sent in headers
• request payload is valid JSON
• required fields are present
• endpoint-specific parameters are supported
• H2I requests stay within allowed HTML and render limits
• upload requests stay within upload and media limits
• request rate and usage stay within the limits for the current plan
• signed output URLs are used exactly as returned
• request_id is logged for failed requests

How to use this page #

Use this page when a request is failing and you need a practical debugging flow. For the full public error catalog, use Error Codes. For scenario-based troubleshooting, use Common Errors. For exact customer-facing limits, use Rate Limits and Usage Limits.