Errors

Failed API calls return JSON with success: false and an error object.

Error shape

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Human-readable description",
    "docs_url": "https://docs.docconvert.io/errors#INVALID_API_KEY"
  }
}

Error codes

INVALID_API_KEY

HTTP 401 — Missing or unknown API key. Send a valid X-API-Key header.

PAYMENT_REQUIRED

HTTP 402 — Key exists but billing is not active. Complete Stripe checkout after registration.

QUOTA_EXCEEDED

HTTP 429 — Monthly conversion limit reached for your plan. Upgrade via billing or wait until the next billing period.

RATE_LIMITED

HTTP 429 — More than 60 requests per minute per API key (or IP when unauthenticated). Back off and retry.

VALIDATION_ERROR

HTTP 400 — Missing required fields, invalid JSON in options, empty content, or invalid URL mode.

INVALID_FORMAT

HTTP 400 — Unsupported input_format/output_format pair or unknown format name.

FILE_TOO_LARGE

HTTP 400 — Input exceeds the 1 MB synchronous limit.

UNSUPPORTED_MEDIA_TYPE

HTTP 415 — Use application/json or multipart/form-data.

CONVERSION_FAILED

HTTP 500 — Conversion engine failed (corrupt file, unreadable URL, etc.).

HEAVY_CONVERTER_DISABLED

HTTP 503 — URL→PDF or LibreOffice-backed conversion unavailable in this environment.

MISSING_EMAIL

HTTP 400 — POST /v1/auth/register requires an email field.

INVALID_PLAN

HTTP 400 — POST /v1/billing/checkout received an unknown plan name.

NOT_FOUND

HTTP 404 — Unknown route or method.

INTERNAL_ERROR

HTTP 500 — Unexpected server error.