Error Handling

Understanding error responses and status codes in the Chunkr API

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:

Python

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