12 min read

Error Codes

Complete reference of DocuRift API error codes with troubleshooting guides

This page provides a comprehensive reference of all error codes returned by the DocuRift API. Each error includes the code, HTTP status, description, and recommended resolution. Use this guide to troubleshoot issues and understand what each error means and how to fix it.

Quick Troubleshooting Guide

Having issues with DocuRift? Here's how to diagnose common problems:

  • Getting 401 errors? Your API key is invalid or missing. Check that you're including the X-API-Key header with a valid key from your dashboard.
  • Getting 402 errors? You've run out of credits. Purchase more credits or check your balance in the dashboard.
  • Getting 429 errors? You're sending too many requests. Implement exponential backoff and retry logic.
  • Getting 500 errors? This is a server-side issue. Retry the request with exponential backoff, and contact support if it persists.

Authentication Errors

These errors occur when there are issues with API key authentication.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | UNAUTHORIZED | 401 | No API key provided in the request | Add the X-API-Key header to your request | | INVALID_API_KEY | 401 | The API key is invalid, malformed, or has been revoked | Verify your API key in the dashboard | | API_KEY_EXPIRED | 401 | The API key has expired | Generate a new API key in the dashboard | | API_KEY_DISABLED | 401 | The API key has been manually disabled | Re-enable the key or create a new one |

Example Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "details": {
      "keyPrefix": "dk_live_abc..."
    }
  },
  "requestId": "req_7f8a9b0c1d2e"
}

Credit Errors

These errors occur when there are insufficient credits to complete the operation.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | INSUFFICIENT_CREDITS | 402 | Not enough credits to process the document | Purchase more credits or upgrade your plan | | FREE_TIER_EXHAUSTED | 402 | Free tier page limit has been used | Create an account and add payment method | | CREDIT_PURCHASE_REQUIRED | 402 | Account requires credit purchase to continue | Add credits via the billing dashboard |

Example Response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits to process this document",
    "details": {
      "required": 5,
      "available": 2,
      "pageCount": 5
    }
  },
  "requestId": "req_3e4f5a6b7c8d"
}

Handling Credit Errors

if (error.code === 'INSUFFICIENT_CREDITS') {
  const { required, available } = error.details;
  console.log(`Need ${required - available} more credits`);
  // Redirect to billing or show upgrade modal
}

Document Errors

These errors occur when there are issues with the uploaded document.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | INVALID_FILE_TYPE | 400 | The uploaded file format is not supported | Use PDF, PNG, JPG, JPEG, or WEBP formats | | FILE_TOO_LARGE | 413 | The file exceeds the 50MB size limit | Compress the file or split into smaller documents | | INVALID_DOCUMENT_TYPE | 400 | The specified documentType is not valid | Use a valid type: invoice, receipt, bank_statement, id_document, passport, utility_bill, medical_record, contract, custom | | DOCUMENT_NOT_FOUND | 404 | The requested document does not exist | Verify the document ID and check it hasn't been deleted | | DOCUMENT_EXPIRED | 410 | The document has been automatically deleted | Re-upload the document (documents expire after 24 hours) | | EMPTY_FILE | 400 | The uploaded file is empty | Ensure the file contains data before uploading | | CORRUPTED_FILE | 400 | The file is corrupted and cannot be read | Try re-exporting or re-scanning the document |

Example Response

{
  "success": false,
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "Unsupported file format. Please upload PDF, PNG, JPG, or WEBP",
    "details": {
      "receivedType": "application/vnd.ms-excel",
      "supportedTypes": ["application/pdf", "image/png", "image/jpeg", "image/webp"]
    }
  },
  "requestId": "req_1a2b3c4d5e6f"
}

Valid Document Types

| Type | Description | |------|-------------| | invoice | Invoices and bills | | receipt | Purchase receipts | | bank_statement | Bank account statements | | id_document | ID cards and driver's licenses | | passport | Passport documents | | utility_bill | Utility and service bills | | medical_record | Medical and health records | | contract | Legal contracts and agreements | | custom | Custom document type with user-defined fields |

Processing Errors

These errors occur during document processing.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | PROCESSING_FAILED | 500 | OCR or extraction failed | Retry the request; contact support if persistent | | PROCESSING_TIMEOUT | 500 | Processing took too long | Use async mode for large documents | | OCR_FAILED | 500 | Text recognition failed | Ensure document is clear and readable | | EXTRACTION_FAILED | 500 | Data extraction failed | Verify document matches the specified type | | CONCURRENT_LIMIT_EXCEEDED | 429 | More than 5 concurrent requests | Wait for current requests to complete | | LOW_QUALITY_IMAGE | 400 | Image quality too low for processing | Upload a higher resolution image (min 150 DPI) |

Example Response

{
  "success": false,
  "error": {
    "code": "CONCURRENT_LIMIT_EXCEEDED",
    "message": "Maximum concurrent request limit (5) exceeded",
    "details": {
      "currentConcurrent": 5,
      "maxConcurrent": 5,
      "retryAfter": 3
    }
  },
  "requestId": "req_9g8h7i6j5k4l"
}

Handling Concurrent Limits

import asyncio

async def process_with_backoff(file, api_key, attempt=0):
    try:
        return await process_document(file, api_key)
    except DocuRiftError as e:
        if e.code == 'CONCURRENT_LIMIT_EXCEEDED':
            retry_after = e.details.get('retryAfter', 3)
            await asyncio.sleep(retry_after)
            return await process_with_backoff(file, api_key, attempt + 1)
        raise

Webhook Errors

These errors occur when there are issues with webhook configuration or delivery.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | INVALID_WEBHOOK_URL | 400 | The webhook URL is malformed or invalid | Provide a valid HTTPS URL | | WEBHOOK_DELIVERY_FAILED | 500 | Could not deliver webhook to your endpoint | Check your endpoint is accessible and returns 2xx | | WEBHOOK_TIMEOUT | 500 | Your endpoint took too long to respond | Ensure response within 30 seconds | | WEBHOOK_SSL_ERROR | 400 | SSL certificate validation failed | Use a valid SSL certificate | | WEBHOOK_MAX_RETRIES | 500 | Maximum delivery attempts (5) exceeded | Check endpoint logs; webhook will not retry again |

Example Response

{
  "success": false,
  "error": {
    "code": "INVALID_WEBHOOK_URL",
    "message": "Invalid webhook URL provided",
    "details": {
      "url": "http://example.com/webhook",
      "reason": "URL must use HTTPS protocol"
    }
  },
  "requestId": "req_2m3n4o5p6q7r"
}

Webhook Requirements

  • Must use HTTPS (HTTP not accepted)
  • Must respond within 30 seconds
  • Must return 2xx status code
  • Must have valid SSL certificate

Rate Limit Errors

These errors occur when rate limits are exceeded.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | RATE_LIMIT_EXCEEDED | 429 | Too many requests in the time window | Implement exponential backoff; see Rate Limits | | IP_BLOCKED | 403 | IP temporarily blocked due to abuse | Wait 24 hours or contact support | | BURST_LIMIT_EXCEEDED | 429 | Too many requests in a short burst | Space out requests more evenly |

Example Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down your requests",
    "details": {
      "limit": 100,
      "window": "60s",
      "retryAfter": 45,
      "resetAt": "2024-01-15T10:31:00Z"
    }
  },
  "requestId": "req_8s9t0u1v2w3x"
}

Rate Limit Headers

Every response includes rate limit information:

| Header | Description | |--------|-------------| | X-RateLimit-Limit | Maximum requests per window | | X-RateLimit-Remaining | Requests remaining in window | | X-RateLimit-Reset | Unix timestamp when limit resets | | Retry-After | Seconds to wait (only on 429) |

Validation Errors

These errors occur when request parameters are invalid.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | VALIDATION_ERROR | 400 | One or more request parameters are invalid | Check the details field for specific issues | | MISSING_REQUIRED_FIELD | 400 | A required field is missing | Include all required fields in your request | | INVALID_FIELD_VALUE | 400 | A field value is invalid | Check the field format and constraints | | INVALID_JSON | 400 | Request body is not valid JSON | Verify JSON syntax |

Example Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "documentType",
          "message": "Invalid document type 'invocie'. Did you mean 'invoice'?"
        },
        {
          "field": "webhookUrl",
          "message": "Must be a valid HTTPS URL"
        }
      ]
    }
  },
  "requestId": "req_4y5z6a7b8c9d"
}

Job Errors

These errors occur when working with asynchronous processing jobs.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | JOB_NOT_FOUND | 404 | The specified job ID does not exist | Verify the job ID from the initial request | | JOB_EXPIRED | 410 | The job result has expired | Re-submit the document for processing | | JOB_CANCELLED | 400 | The job was cancelled | Submit a new processing request | | JOB_FAILED | 500 | The job failed during processing | Check error details and retry |

Example Response

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job not found or has expired",
    "details": {
      "jobId": "job_abc123",
      "expiresAfter": "24 hours"
    }
  },
  "requestId": "req_0e1f2g3h4i5j"
}

Server Errors

These errors indicate server-side issues.

| Code | HTTP | Description | Resolution | |------|------|-------------|------------| | INTERNAL_ERROR | 500 | An unexpected server error occurred | Retry with exponential backoff; contact support if persistent | | SERVICE_UNAVAILABLE | 503 | The service is temporarily unavailable | Retry after a few minutes | | MAINTENANCE_MODE | 503 | The API is under maintenance | Check status page for updates | | DEPENDENCY_ERROR | 500 | An internal dependency failed | Retry the request |

Example Response

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again",
    "details": {
      "supportId": "sup_xyz789"
    }
  },
  "requestId": "req_6k7l8m9n0o1p"
}

Error Code Quick Reference

By HTTP Status

| Status | Codes | |--------|-------| | 400 | VALIDATION_ERROR, INVALID_FILE_TYPE, INVALID_DOCUMENT_TYPE, MISSING_REQUIRED_FIELD, INVALID_FIELD_VALUE, INVALID_JSON, EMPTY_FILE, CORRUPTED_FILE, LOW_QUALITY_IMAGE, INVALID_WEBHOOK_URL, WEBHOOK_SSL_ERROR, JOB_CANCELLED | | 401 | UNAUTHORIZED, INVALID_API_KEY, API_KEY_EXPIRED, API_KEY_DISABLED | | 402 | INSUFFICIENT_CREDITS, FREE_TIER_EXHAUSTED, CREDIT_PURCHASE_REQUIRED | | 403 | IP_BLOCKED | | 404 | DOCUMENT_NOT_FOUND, JOB_NOT_FOUND | | 410 | DOCUMENT_EXPIRED, JOB_EXPIRED | | 413 | FILE_TOO_LARGE | | 429 | RATE_LIMIT_EXCEEDED, CONCURRENT_LIMIT_EXCEEDED, BURST_LIMIT_EXCEEDED | | 500 | INTERNAL_ERROR, PROCESSING_FAILED, PROCESSING_TIMEOUT, OCR_FAILED, EXTRACTION_FAILED, WEBHOOK_DELIVERY_FAILED, WEBHOOK_TIMEOUT, WEBHOOK_MAX_RETRIES, JOB_FAILED, DEPENDENCY_ERROR | | 503 | SERVICE_UNAVAILABLE, MAINTENANCE_MODE |

By Category

| Category | Codes | |----------|-------| | Auth | UNAUTHORIZED, INVALID_API_KEY, API_KEY_EXPIRED, API_KEY_DISABLED | | Credits | INSUFFICIENT_CREDITS, FREE_TIER_EXHAUSTED, CREDIT_PURCHASE_REQUIRED | | Documents | INVALID_FILE_TYPE, FILE_TOO_LARGE, INVALID_DOCUMENT_TYPE, DOCUMENT_NOT_FOUND, DOCUMENT_EXPIRED, EMPTY_FILE, CORRUPTED_FILE, LOW_QUALITY_IMAGE | | Processing | PROCESSING_FAILED, PROCESSING_TIMEOUT, OCR_FAILED, EXTRACTION_FAILED, CONCURRENT_LIMIT_EXCEEDED | | Webhooks | INVALID_WEBHOOK_URL, WEBHOOK_DELIVERY_FAILED, WEBHOOK_TIMEOUT, WEBHOOK_SSL_ERROR, WEBHOOK_MAX_RETRIES | | Rate Limits | RATE_LIMIT_EXCEEDED, IP_BLOCKED, BURST_LIMIT_EXCEEDED | | Validation | VALIDATION_ERROR, MISSING_REQUIRED_FIELD, INVALID_FIELD_VALUE, INVALID_JSON | | Jobs | JOB_NOT_FOUND, JOB_EXPIRED, JOB_CANCELLED, JOB_FAILED | | Server | INTERNAL_ERROR, SERVICE_UNAVAILABLE, MAINTENANCE_MODE, DEPENDENCY_ERROR |

Frequently Asked Questions

What does INVALID_API_KEY mean?

The INVALID_API_KEY error (HTTP 401) means the API key you provided is either malformed, has been revoked, or doesn't exist. To fix this, go to your DocuRift dashboard, create a new API key, and update your application with the new key. Make sure you're using the correct key format (starts with dk_live_ for production or dk_test_ for testing).

How do I fix INSUFFICIENT_CREDITS error?

The INSUFFICIENT_CREDITS error (HTTP 402) occurs when you don't have enough credits to process a document. Each document consumes credits based on its type and page count. To resolve this, log into your DocuRift dashboard and purchase more credits. The error response includes required and available fields showing exactly how many credits you need.

Why am I getting RATE_LIMIT_EXCEEDED?

The RATE_LIMIT_EXCEEDED error (HTTP 429) means you're sending requests faster than your plan allows. Implement exponential backoff in your application: when you receive this error, wait for the number of seconds specified in the retryAfter field or the Retry-After header before retrying. Consider upgrading your plan if you consistently hit rate limits.

What should I do if I get PROCESSING_FAILED?

The PROCESSING_FAILED error (HTTP 500) indicates the document couldn't be processed. This can happen if the document is blurry, has unusual formatting, or is in a language we don't support well. Try re-uploading a clearer version of the document. If the error persists, contact DocuRift support with your requestId for investigation.

How long do documents stay in the system?

Documents are automatically deleted after 24 hours, which can cause DOCUMENT_EXPIRED or JOB_EXPIRED errors. If you need the results after 24 hours, make sure to store them in your own system immediately after processing completes.

What file formats does DocuRift support?

DocuRift supports PDF, PNG, JPG, JPEG, and WEBP formats. If you upload an unsupported format, you'll receive an INVALID_FILE_TYPE error. Files must be under 50MB for async processing or 10MB for sync processing. If your file is too large, you'll get a FILE_TOO_LARGE error.

How do I handle concurrent request limits?

The CONCURRENT_LIMIT_EXCEEDED error (HTTP 429) occurs when you have more than 5 simultaneous requests processing. Implement a queue in your application to ensure you don't exceed this limit. The error response includes retryAfter indicating when you can retry.

Why is my webhook not receiving events?

Webhook issues can cause WEBHOOK_DELIVERY_FAILED, WEBHOOK_TIMEOUT, or WEBHOOK_SSL_ERROR errors. Ensure your webhook endpoint uses HTTPS with a valid SSL certificate, responds within 30 seconds, and returns a 2xx status code. Check your server logs to debug incoming webhook requests.