Skip to main content

API Errors

Use this page when a Public API request fails and you need the fastest path to the likely fix.

Start With The Status Code​

  • 400: request shape or validation issue, including malformed filename_columns
  • 401: auth header missing or invalid
  • 403: key is revoked, expired, inactive, or the account is not eligible
  • 409: Idempotency-Key payload mismatch
  • 413: file or output package is too large
  • 422: malformed PDF or batch size/shape is unacceptable
  • 500: retry after checking delivery or server-side failure details

Common Fixes​

BF_EXPORT_API_KEY_REQUIRED or BF_EXPORT_API_KEY_INVALID​

  • confirm the request uses Authorization: Bearer <token>
  • confirm the token was copied exactly once from the create response

INVALID_IDEMPOTENCY_KEY or IDEMPOTENCY_KEY_PAYLOAD_MISMATCH​

  • send Idempotency-Key on create requests
  • generate a new idempotency key for a new logical request
  • do not reuse a previous idempotency key for a changed payload
  • use X-Request-Id only for tracing/support correlation
  • remember that create-side 429 responses can still happen before replay lookup

INVALID_FILENAME_COLUMNS or TOO_MANY_FILENAME_COLUMNS​

  • send filename_columns only when you want custom row suffixes
  • send exactly one filename_columns multipart field and make it a JSON string array
  • INVALID_FILENAME_COLUMNS means the field was malformed JSON, parsed to null, was not an array, contained non-string entries, or was sent more than once
  • TOO_MANY_FILENAME_COLUMNS means the array contained more than 3 entries
  • repeated column keys are allowed, and unknown or unavailable selected columns are not create-time shape errors; Doqlo handles them best-effort per row

Validation Errors​

  • confirm you uploaded pdf and doqlo_file
  • confirm you provided exactly one of rows_json or csv_file
  • if .doqlo validation fails, re-export the package from the web Bulk Fill editor and confirm the package itself is valid
  • static QR/barcode overlay issues are not reported as create-time schema errors on the public API; they are skipped later and reported in manifest.json
  • if the PDF cannot be opened, confirm it is a readable PDF and still within current size and page limits
  • if row data is malformed, validate the JSON or CSV before resubmitting
  • if the job completes but some rows are missing or incomplete, inspect manifest.json inside the ZIP artifact for row-level warnings and errors
  • confirm the PDF is valid and within current size/page limits

Threshold Failures​

  • inspect error.details on the failed job envelope
  • compare failed_row_percent against your submitted max_failed_row_percent
  • remember the threshold counts failed rows, not skipped overlays inside a produced row
  • no download artifact is exposed for a threshold-failed job

Download Errors​

  • if DELIVERY_NOT_FOUND, the job may still be readable but the current delivery is no longer available
  • if DELIVERY_TEMPORARILY_UNAVAILABLE, retry the download request later