Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": "Human-readable error message",
  "detail": "Additional context",
  "code": "error_code"
}

HTTP Status Codes

Code	Meaning	When
400	Bad Request	Invalid parameters, missing required fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key revoked, expired, or insufficient permissions
404	Not Found	Job or resource doesn't exist
422	Unprocessable Entity	Processing failed (bad document, no form fields, etc.)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Common Errors

Authentication

// 401 — Missing API key
{
  "detail": "Not authenticated"
}

// 401 — Invalid API key
{
  "detail": "Could not validate credentials"
}

// 403 — Key revoked
{
  "detail": "API key has been revoked"
}

Document Processing

// 422 — Unsupported file type
{
  "error": "Unsupported file type",
  "detail": "Accepted formats: PDF, PNG, JPG, JPEG, BMP, TIFF"
}

// 422 — No form fields in PDF
{
  "error": "No fillable form fields detected",
  "code": "no_form_fields"
}

// 422 — OCR failed
{
  "error": "Could not extract text from document",
  "code": "processing_error"
}

Job Errors

// 404 — Job not found
{
  "detail": "Job not found"
}

Error Handling Best Practice

import requests

response = requests.post(
    "https://developer-api.qomplement.com/v1/extract",
    headers={"Authorization": "Bearer sd_YOUR_API_KEY"},
    files={"file": open("document.pdf", "rb")},
)

if response.status_code == 200:
    result = response.json()
    # Process result...
elif response.status_code == 202:
    job = response.json()
    # Poll for results...
elif response.status_code == 401:
    print("Check your API key")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 5))
    print(f"Rate limited — retry in {retry_after}s")
else:
    error = response.json()
    print(f"Error {response.status_code}: {error.get('error', error.get('detail'))}")