Error Handling

The Chunkr API uses conventional HTTP status codes to indicate the success or failure of requests. Error responses include descriptive messages to help you understand and resolve issues.

HTTP Status Codes

Success Codes

Status Code	Description
`200 OK`	Request succeeded

Client Error Codes

Status Code	Description
`400 Bad Request`	Invalid request parameters or malformed request
`401 Unauthorized`	Authentication failed or missing credentials
`404 Not Found`	Requested resource does not exist
`429 Too Many Requests`	Rate limit exceeded

Server Error Codes

Status Code	Description
`500 Internal Server Error`	An error occurred on the server

Error Response Format

Error responses return a plain text message in the response body describing the error:

Error message text

For structured error handling, check both the HTTP status code and the response body message.

Common Errors

Authentication Errors (401)

Missing Authorization Header

GET /api/v1/task/{task_id}
# Status: 401 Unauthorized
# Response: "Authorization header is missing"

Cause: The Authorization header is not included in the request. Solution: Add the Authorization header with your API key:

curl -H "Authorization: YOUR_API_KEY" \
  https://api.chunkr.ai/api/v1/task/{task_id}

Invalid or Inactive API Key

# Status: 401 Unauthorized
# Response: "Invalid or inactive API key"

Cause: The API key is incorrect, has been revoked, or marked as inactive. Solution:

Verify your API key is correct
Generate a new API key from your dashboard
Ensure the key hasn’t been deactivated

Invalid Token Payload

# Status: 401 Unauthorized  
# Response: "Invalid token payload"

Cause: The Bearer token is malformed, expired, or has an invalid signature. Solution:

Refresh your OAuth token
Verify the token is properly formatted
Check that the token hasn’t expired

Validation Errors (400)

Invalid Base64 Data

POST /api/v1/task/parse
# Status: 400 Bad Request
# Response: "Invalid base64 data"

Cause: The file data provided is not valid base64-encoded content. Solution: Ensure your file is properly base64-encoded:

import base64

with open('document.pdf', 'rb') as f:
    file_data = base64.b64encode(f.read()).decode('utf-8')

Unsupported File Type

POST /api/v1/task/parse
# Status: 400 Bad Request
# Response: "Unsupported file type"

Cause: The file type is not supported by Chunkr. Solution: Use a supported document format (PDF, images, etc.).

File Must Have a Filename

POST /api/v1/task
# Status: 400 Bad Request
# Response: "File must have a filename"

Cause: When using multipart form upload, the file field is missing a filename. Solution: Ensure your multipart request includes a filename for the file field.

Task Cannot Be Updated

PATCH /api/v1/task/{task_id}/parse
# Status: 400 Bad Request
# Response: "Task cannot be updated: status is Processing"

Cause: You’re trying to update a task that’s not in a Succeeded or Failed state. Solution: Wait for the task to complete before attempting to update it.

Task Cannot Be Cancelled

GET /api/v1/task/{task_id}/cancel
# Status: 400 Bad Request  
# Response: "Task cannot be cancelled: status is Processing"

Cause: Only tasks in Starting status can be cancelled. Solution: You cannot cancel tasks that have already begun processing.

Resource Errors (404)

Task Not Found

GET /api/v1/task/{task_id}
# Status: 404 Not Found
# Response: "Task not found"

Cause: The task ID doesn’t exist, has expired, or belongs to a different user. Solution:

Verify the task ID is correct
Check if the task has expired (expired tasks are automatically deleted)
Ensure you’re using the same API key that created the task

Rate Limiting Errors (429)

Usage Limit Exceeded

POST /api/v1/task/parse
# Status: 429 Too Many Requests
# Response: "Usage limit exceeded"

Cause: You’ve exceeded the rate limit for your account or service tier. Solution: Implement exponential backoff and retry logic:

import time
import requests

def create_task_with_retry(data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            'https://api.chunkr.ai/api/v1/task/parse',
            headers={'Authorization': 'YOUR_API_KEY'},
            json=data
        )
        
        if response.status_code == 429:
            wait_time = (2 ** attempt)  # Exponential backoff
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

When encountering rate limits, always implement exponential backoff rather than immediately retrying.

Server Errors (500)

Internal Server Error

# Status: 500 Internal Server Error
# Response: "Failed to create task" or specific error message

Cause: An unexpected error occurred on the server. Solution:

Check if the error is transient by retrying the request
Verify your request payload is valid
Contact support if the error persists

Database Connection Error

# Status: 500 Internal Server Error
# Response: "Failed to get client" or "Database connection error"

Cause: The server couldn’t establish a database connection. Solution: This is a server-side issue. Retry the request or contact support.

Failed to Process File

POST /api/v1/task/parse
# Status: 500 Internal Server Error
# Response: "Failed to process file"

Cause: The server encountered an error while processing your file. Solution:

Verify your file is not corrupted
Check that the file size is within limits (max 1GB)
Try with a different file to isolate the issue

Task-Specific Errors

Task Status Messages

Tasks can fail with specific messages in the message field:

Page Limit Exceeded

{
  "task_id": "...",
  "status": "Failed",
  "message": "Page limit exceeded"
}

Cause: The document exceeds your account’s page processing limit. Solution: Upgrade your plan or split the document into smaller files.

Task Timed Out

{
  "task_id": "...",
  "status": "Failed",  
  "message": "Task timed out"
}

Cause: The task exceeded the maximum processing time (default 10 minutes). Solution:

The document may be too complex
Try with a smaller document
Contact support if timeouts persist

Error Handling Best Practices

1. Check Status Codes

Always check the HTTP status code before parsing the response:

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
else:
    error_message = response.text
    print(f"Error {response.status_code}: {error_message}")

2. Implement Retry Logic

For transient errors (429, 500), implement retry logic with exponential backoff:

from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

retry_strategy = Retry(
    total=3,
    status_forcelist=[429, 500, 502, 503, 504],
    backoff_factor=1
)
adapter = HTTPAdapter(max_retries=retry_strategy)
http = requests.Session()
http.mount("https://", adapter)

3. Handle Specific Error Cases

Different errors require different handling:

def handle_api_error(response):
    if response.status_code == 401:
        # Authentication error - check API key
        raise AuthenticationError("Invalid API key")
    elif response.status_code == 404:
        # Resource not found - task may have expired
        raise NotFoundError("Task not found or expired")  
    elif response.status_code == 429:
        # Rate limited - implement backoff
        raise RateLimitError("Rate limit exceeded")
    elif response.status_code >= 500:
        # Server error - retry may help
        raise ServerError("Server error occurred")
    else:
        raise APIError(f"API error: {response.text}")

4. Log Errors for Debugging

Log both successful and failed requests for debugging:

import logging

logger = logging.getLogger(__name__)

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    logger.info(f"Task created: {response.json()['task_id']}")
except requests.exceptions.RequestException as e:
    logger.error(f"API request failed: {e}")
    logger.error(f"Response: {e.response.text if e.response else 'No response'}")
    raise

Next Steps

Authentication

Review authentication methods and requirements

API Overview

Learn about rate limits and API capabilities

Task Endpoints

Explore task management endpoints

Overview

Tasks

Models

Documentation Index

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Error Response Format

​Common Errors

​Authentication Errors (401)

​Missing Authorization Header

​Invalid or Inactive API Key

​Invalid Token Payload

​Validation Errors (400)

​Invalid Base64 Data

​Unsupported File Type

​File Must Have a Filename

​Task Cannot Be Updated

​Task Cannot Be Cancelled

​Resource Errors (404)

​Task Not Found

​Rate Limiting Errors (429)

​Usage Limit Exceeded

​Server Errors (500)

​Internal Server Error

​Database Connection Error

​Failed to Process File

​Task-Specific Errors

​Task Status Messages

​Page Limit Exceeded

​Task Timed Out

​Error Handling Best Practices

​1. Check Status Codes

​2. Implement Retry Logic

​3. Handle Specific Error Cases

​4. Log Errors for Debugging

​Next Steps

Authentication

API Overview

Task Endpoints

Build docs developers (and LLMs) love

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Response Format

Common Errors

Authentication Errors (401)

Missing Authorization Header

Invalid or Inactive API Key

Invalid Token Payload

Validation Errors (400)

Invalid Base64 Data

Unsupported File Type

File Must Have a Filename

Task Cannot Be Updated

Task Cannot Be Cancelled

Resource Errors (404)

Task Not Found

Rate Limiting Errors (429)

Usage Limit Exceeded

Server Errors (500)

Internal Server Error

Database Connection Error

Failed to Process File

Task-Specific Errors

Task Status Messages

Page Limit Exceeded

Task Timed Out

Error Handling Best Practices

1. Check Status Codes

2. Implement Retry Logic

3. Handle Specific Error Cases

4. Log Errors for Debugging

Next Steps