Errors

When a request fails, the API returns an appropriate HTTP status code with a JSON body containing an error field.

Error Response Format

{
  "error": "description of what went wrong"
}

Error Reference

400 Bad Request

The request is malformed or the file is not a supported type.

Causes:

File is not a valid PDF, PNG, or JPEG (detected by magic bytes)
File exceeds the 10 MB size limit
Missing file field in multipart form data
Document exceeds 2,000 pages

Examples:

{
  "error": "unsupported file type: expected PDF, PNG, or JPEG"
}

{
  "error": "file too large: 14.2 MB exceeds 10 MB limit"
}

{
  "error": "missing file field in multipart form"
}

401 Unauthorized

The API key is missing, invalid, or revoked.

Examples:

{
  "error": "missing X-API-Key header"
}

{
  "error": "invalid API key"
}

402 Payment Required

Your account does not have enough credits to process the document. The error message includes how many credits are needed and how many you have.

Example:

{
  "error": "insufficient credits: need 5, have 2"
}

Purchase more credits in the Dashboard or see Rate Limits & Credits for pricing.

429 Too Many Requests

You have exceeded the rate limit of 1 request per second.

Example:

{
  "error": "rate limit exceeded"
}

Wait at least 1 second before retrying. For programmatic usage, add a delay between requests:

import time

for file_path in file_paths:
    resp = requests.post(
        "https://api.bitparse.ai/parse",
        headers={"X-API-Key": "bp_YOUR_API_KEY"},
        files={"file": open(file_path, "rb")},
    )
    print(resp.json())
    time.sleep(1)  # respect rate limit

500 Internal Server Error

An unexpected error occurred during processing.

Example:

{
  "error": "internal server error"
}

If this persists, contact support@bitparse.ai with the file you are trying to parse.

Error Handling Best Practices

Status	Retry?	Action
400	No	Fix the request (file type, size, form data)
401	No	Check your API key
402	No	Purchase more credits
429	Yes	Wait 1 second and retry
500	Yes	Retry with exponential backoff; contact support if persistent

Retry Example with Backoff

import time
import requests

def parse_with_retry(file_path, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://api.bitparse.ai/parse",
            headers={"X-API-Key": api_key},
            files={"file": open(file_path, "rb")},
        )

        if resp.status_code == 200:
            return resp.json()
        elif resp.status_code == 429:
            time.sleep(1)
        elif resp.status_code >= 500:
            time.sleep(2 ** attempt)
        else:
            resp.raise_for_status()

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

On this page