Guides

Error Handling

Learn how to handle API errors gracefully and provide a good user experience.

Error Response Format

All API errors return a consistent JSON format with an error message and optional details.

json

{
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "details": {}
}

HTTP Status Codes

400

Bad Request

Invalid request body or missing required fields

401

Unauthorized

Missing or invalid API key

403

Forbidden

API key doesn't have permission for this resource

404

Not Found

The requested resource doesn't exist

422

Unprocessable Entity

Could not extract data from the document

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Example Error Handling

javascript

async function extractDocument(imageUrl) {
  try {
    const response = await fetch('/api/mrz/scan', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.DOCSCAN_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ imageUrl }),
    });

    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key');
        case 422:
          throw new Error('Could not extract data from image');
        case 429:
          throw new Error('Rate limit exceeded, please retry later');
        default:
          throw new Error(error.message || 'Unknown error');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('Extraction failed:', error);
    throw error;
  }
}

Document Types Best Practices