Error Handling

The Docspeed customer API uses standard HTTP status codes with structured error bodies.

Common statuses

• 400 invalid request shape or unsupported input combination
• 401 missing or invalid bearer token
• 402 insufficient credits
• 422 policy or validation failure
• 429 rate limit exceeded
• 502 provider execution failure
• 503 temporary unavailability

cURL

curl -sS -X POST "https://api.docspeed.ai/v1/extract" \
  -H "Authorization: Bearer ${DOCSPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "not a PDF or image"}, "execution_mode": "sync"}'

Python

import requests

response = requests.post(
    "https://api.docspeed.ai/v1/extract",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"input": {"text": "not a PDF or image"}, "execution_mode": "sync"},
    timeout=120,
)

if not response.ok:
    print(response.status_code, response.json())

TypeScript

const response = await fetch("https://api.docspeed.ai/v1/extract", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: { text: "not a PDF or image" },
    execution_mode: "sync",
  }),
});

if (!response.ok) {
  console.error(response.status, await response.json());
}

Example error body

{
  "detail": {
    "code": "invalid_input",
    "message": "Schema-based extraction currently requires an image or PDF input.",
    "details": null
  }
}