Error Reference

This section covers error handling best practices and a complete reference of error codes. Proper error handling is essential for building robust integrations with DocuRift. By understanding how our API communicates errors, you can create applications that gracefully handle edge cases, provide helpful feedback to users, and automatically recover from transient failures.

Overview

DocuRift's API uses standard HTTP status codes and returns detailed error information to help you debug issues quickly. Every error response includes a unique request ID, a machine-readable error code, and a human-readable message. This consistent structure makes it easy to log errors, display appropriate messages to users, and implement automatic retry logic where appropriate.

When an error occurs, the API always returns a JSON response with success: false and an error object containing all the information you need to diagnose and resolve the issue. We recommend logging the full error response during development to understand the full context of each error.

Error Handling Guides

Error Response Format

All errors follow this consistent structure, making it easy to parse and handle errors programmatically:

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

The code field contains a machine-readable identifier you can use in your error handling logic. The message field provides a human-readable explanation suitable for logging or displaying to developers. The optional details object contains additional context specific to the error type.

Common HTTP Status Codes

DocuRift uses standard HTTP status codes to indicate the general category of the error. Here are the most common codes you'll encounter:

| Code | Meaning | Common Causes | |------|---------|---------------| | 400 | Bad Request | Invalid parameters, malformed request, unsupported file format | | 401 | Unauthorized | Invalid or missing API key | | 402 | Payment Required | Insufficient credits to process the document | | 403 | Forbidden | Access denied to resource, API key lacks required permissions | | 404 | Not Found | Document or job doesn't exist | | 413 | Payload Too Large | File exceeds the 20MB size limit | | 429 | Too Many Requests | Rate limit exceeded, implement backoff | | 500 | Server Error | Internal error, contact support with requestId |

Handling Errors by Category

Different error categories require different handling strategies:

Client Errors (4xx): These indicate a problem with the request. Check your parameters, file format, or API key. These errors typically require fixing the request before retrying.

Rate Limits (429): Implement exponential backoff and retry logic. Our API returns Retry-After headers to indicate when you can retry.

Server Errors (5xx): These are rare and usually transient. Implement retry logic with exponential backoff. If errors persist, contact support with your requestId.

Quick Debugging Tips

1. Check the error code: Each error has a specific code that tells you exactly what went wrong
2. Review the message: The message provides human-readable context for developers
3. Use the requestId: Always include this when contacting support for faster resolution
4. Check your API key: Many errors are caused by invalid, expired, or revoked keys
5. Validate file format: Ensure you're sending PDF, PNG, or JPEG files under 20MB
6. Check your credit balance: Payment Required errors mean you need to purchase more credits

Need Help?

If you're stuck on an error, check our Error Codes reference for detailed information about each error type. For persistent issues, contact support with your requestId and we'll help you resolve the problem quickly.