Skip to main content

​
Error format

All errors return a consistent JSON shape: 
{
  "error": {
    "code": "bad_request",
    "message": "Human-readable description of the problem",
    "doc_url": "https://okrapdf.dev/api-reference/errors"
  }
}

​
Error codes

CodeHTTP StatusDescription
bad_request400Invalid request body or parameters
unauthorized401Missing or invalid API key
forbidden403Valid key but not authorized for this resource
not_found404Job or document does not exist
rate_limit_exceeded429Too many requests - see rate limits
insufficient_credits402Insufficient credit balance — add credits
job_not_ready400Job is still processing — poll status before fetching results
chat_failed500Document chat processing failed
internal_error500Unexpected server error

​
Handling errors

​
Retry strategy

For transient errors (429, 500, 502, 503), use exponential backoff: 
import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 5))
            time.sleep(retry_after)
            continue

        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue

        return resp

    raise Exception(f"Failed after {max_retries} retries")

​
Non-retryable errors

CodeAction
400Fix your request body or parameters
401Check your API key
402Add credits to your account
403Verify you own the resource
404Verify the job ID exists

​
Common mistakes

Missing filename with file_base64 
{"error": {"code": "bad_request", "message": "filename is required when using file_base64"}}
Fix: Include filename in the request body. Fetching results before completion 
{"error": {"code": "bad_request", "message": "Job not yet completed."}}
Fix: Poll GET /api/v1/jobs/{jobId} until status is completed. Invalid URL 
{"error": {"code": "bad_request", "message": "Invalid URL format. Must be http:// or https://"}}
Fix: Provide a fully-qualified URL starting with http:// or https://.