When an error occurs, the API will return an appropriate HTTP status code along with a JSON response containing error details.

​
Error Response Format

All error responses follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": "Additional error details when available"
  }
}

​
Common Error Codes

CodeDescriptionHTTP Status
UNAUTHORIZEDAuthentication failed401
INVALID_REQUESTMalformed request400
RATE_LIMIT_EXCEEDEDToo many requests429
VALIDATION_ERRORRequest validation failed400
INTERNAL_SERVER_ERRORServer error500

​
Example Error Scenarios

​
Authentication Error

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key provided"
  }
}

​
Rate Limit Error

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

​
Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid file type",
    "details": "Only PDF, JPG, JPEG, and PNG files are allowed"
  }
}

​
Error Categories

Retryable Errors

These errors are temporary and can be resolved by retrying the request after a delay:

  • Rate Limit (429) Exceeded request limits

  • Gateway Errors

    • Bad Gateway (502)
    • Service Unavailable (503)
    • Gateway Timeout (504)

  • Processing Failures Temporary processing issues

Non-Retryable Errors

These errors require fixes before retrying:

  • Authentication (401, 403) Invalid or unauthorized API key

  • Validation (400) Invalid request parameters

  • Not Found (404) Resource doesn’t exist

  • Processing Failures Permanent processing errors

​
HTTP Status Codes

​
2xx
number

Successful requests

​
4xx
number

Client errors

​
5xx
number

Server errors

​
Error Handling Best Practices

​
1. Check Success Flag

Always check the success field in the response:

const response = await api.processDocument(fileId);
if (!response.success) {
  // Handle error
  console.error(response.error.message);
  return;
}

​
2. Implement Retry Logic

Implement exponential backoff for retryable errors:

async function makeRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fn();
      return response;
    } catch (error) {
      if (!isRetryableError(error) || i === maxRetries - 1) {
        throw error;
      }
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

function isRetryableError(error) {
  return [
    429, // Rate limit
    502, // Bad gateway
    503, // Service unavailable
    504  // Gateway timeout
  ].includes(error.status);
}

​
3. Handle Rate Limits

Respect rate limit headers and implement backoff:

function handleRateLimit(error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    const retryAfter = error.retry_after || 1;
    return new Promise(resolve => {
      setTimeout(resolve, retryAfter * 1000);
    });
  }
  throw error;
}

​
4. Log Errors

Implement proper error logging:

function logError(error) {
  const errorInfo = {
    code: error.code,
    message: error.message,
    timestamp: new Date().toISOString(),
    requestId: error.requestId
  };
  console.error('API Error:', errorInfo);
}

​
Support

If you encounter persistent errors or need assistance:

AuthenticationRate Limits