Error Handling

DocLD uses standard HTTP status codes and returns structured error responses. For rate limits and auth errors, see Overview.

Error Response Format

All errors follow this structure:


{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Success Codes

Code	Description
200	Request successful
201	Resource created
204	No content (successful deletion)

Client Error Codes

Code	Description
400	Bad Request - Invalid input
401	Unauthorized - Missing or invalid auth
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource conflict
413	Payload Too Large - File too big
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limited

Server Error Codes

Code	Description
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout

Error Codes

Authentication Errors

Code	HTTP	Description
`UNAUTHORIZED`	401	Missing authentication
`INVALID_API_KEY`	401	API key is invalid
`EXPIRED_API_KEY`	401	API key has expired
`FORBIDDEN`	403	Insufficient permissions

Validation Errors

Code	HTTP	Description
`VALIDATION_ERROR`	400	Request validation failed
`INVALID_INPUT`	400	Invalid input format
`MISSING_FIELD`	400	Required field missing
`INVALID_FORMAT`	400	Invalid data format

Resource Errors

Code	HTTP	Description
`NOT_FOUND`	404	Resource not found
`DOCUMENT_NOT_FOUND`	404	Document doesn’t exist
`SCHEMA_NOT_FOUND`	404	Extraction schema not found
`KB_NOT_FOUND`	404	Knowledge base not found

Processing Errors

Code	HTTP	Description
`PROCESSING_ERROR`	500	Processing failed
`OCR_ERROR`	500	OCR failed
`PARSE_ERROR`	500	Document parsing failed
`EXTRACT_ERROR`	500	Extraction failed
`TIMEOUT`	504	Operation timed out

Limit Errors

Code	HTTP	Description
`RATE_LIMITED`	429	Rate limit exceeded
`QUOTA_EXCEEDED`	403	Credit quota exceeded
`FILE_TOO_LARGE`	413	File exceeds size limit
`UNSUPPORTED_FORMAT`	422	File format not supported

Validation Error Details

Validation errors include field-level details:


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "document_id",
          "message": "Required field is missing"
        },
        {
          "field": "schema.fields[0].type",
          "message": "Must be one of: string, number, boolean, date, array, object"
        }
      ]
    }
  }
}

Rate Limit Errors

Rate limit errors include retry information:


{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "details": {
      "retry_after": 60,
      "limit": 60,
      "remaining": 0,
      "reset_at": "2024-01-15T10:31:00Z"
    }
  }
}

Check headers for rate limit status:


X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705322460
Retry-After: 60

Handling Errors

JavaScript Example


async function callAPI(endpoint, options) {
  const response = await fetch(endpoint, options);
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'RATE_LIMITED':
        const retryAfter = error.error.details.retry_after;
        await sleep(retryAfter * 1000);
        return callAPI(endpoint, options);
        
      case 'UNAUTHORIZED':
        throw new Error('Invalid API key');
        
      case 'NOT_FOUND':
        throw new Error('Resource not found');
        
      default:
        throw new Error(error.error.message);
    }
  }
  
  return response.json();
}

Python Example


import requests
import time
 
def call_api(endpoint, headers, data=None):
    response = requests.post(endpoint, headers=headers, json=data)
    
    if response.status_code == 429:
        retry_after = response.json()['error']['details']['retry_after']
        time.sleep(retry_after)
        return call_api(endpoint, headers, data)
    
    if response.status_code == 401:
        raise Exception('Invalid API key')
    
    if response.status_code == 404:
        raise Exception('Resource not found')
    
    response.raise_for_status()
    return response.json()

Best Practices

Check status codes - Always check the HTTP status code first
Parse error body - Extract code and message for handling
Handle rate limits - Implement exponential backoff
Log errors - Keep error logs for debugging
Retry transient errors - Retry 5xx errors with backoff
Don’t retry client errors - 4xx errors won’t succeed on retry

See also: Overview (rate limits, authentication).