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
CORRUPT_DOCUMENTPDF document is invalid or corrupt400
UPLOAD_ERRORFile upload failures400/500
RATE_LIMIT_EXCEEDEDToo many requests429
VALIDATION_ERRORRequest validation failed400
SCHEMA_NOT_FOUNDSchema with the specified ID does not exist404
SCHEMA_EXISTSActive schema with the same name already exists409
INVALID_SCHEMA_TYPEInvalid schema type specified400
SCHEMA_ERRORGeneral schema operation error500
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"
  }
}

​
Corrupt Document Error

{
  "success": false,
  "error": {
    "code": "CORRUPT_DOCUMENT",
    "message": "Some files failed to upload",
    "details": "PDF document is invalid: document appears to be corrupt or invalid"
  }
}

​
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: