Error Handling

This guide covers how to handle errors when using the Parselyze API and provides solutions for common issues.

HTTP Status Codes

The Parselyze API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Code	Description
200	OK - Request successful
201	Created - Resource created successfully

Client Error Codes

Code	Description	Common Causes
400	Bad Request	Missing required parameters, invalid file format
401	Unauthorized	Invalid or missing API key/token
403	Forbidden	Insufficient permissions, quota exceeded
404	Not Found	Template or resource doesn't exist
413	Payload Too Large	File size exceeds limits
415	Unsupported Media Type	Invalid file format
422	Unprocessable Entity	Valid request but processing failed
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Description
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout

Error Response Format

All error responses follow a consistent format:

{
  "error": "Error description",
  "code": "ERROR_CODE",
  "statusCode": 400,
  "timestamp": "2025-05-26T10:30:00Z",
  "path": "/documents/parse",
  "details": {
    // Additional error-specific information
  }
}

Common Errors and Solutions

Authentication Errors

Invalid API Key

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "statusCode": 401
}

Solution: Verify your API key is correct and hasn't expired.

Missing API Key Header

{
  "error": "API key header is required",
  "code": "MISSING_API_KEY",
  "statusCode": 401
}

Solution: Include the x-api-key: YOUR_API_KEY header in your request.

File Processing Errors

Template Required

{
  "error": "Template ID is required for document analysis",
  "code": "TEMPLATE_REQUIRED",
  "statusCode": 400
}

Solution: Provide a valid template ID. Templates must be created via the web interface at parselyze.com.

Template Not Found

{
  "error": "Template not found",
  "code": "TEMPLATE_NOT_FOUND",
  "statusCode": 404
}

Solution: Verify the template ID exists and you have access to it. Templates can only be created via the web interface.

Unsupported File Format

{
  "error": "Unsupported file format",
  "code": "UNSUPPORTED_FORMAT",
  "statusCode": 415,
  "details": {
    "supportedFormats": ["pdf", "png", "jpg", "jpeg", "zip"]
  }
}

Solution: Convert your file to a supported format.

File Too Large

{
  "error": "File size exceeds maximum limit",
  "code": "FILE_TOO_LARGE",
  "statusCode": 413,
  "details": {
    "maxSize": "50MB",
    "receivedSize": "75MB"
  }
}

Solution: Reduce file size or split into smaller files.

Corrupted File

{
  "error": "File appears to be corrupted or unreadable",
  "code": "CORRUPTED_FILE",
  "statusCode": 422
}

Solution: Verify file integrity and try uploading again.

Multiple Documents (Premium Feature)

{
  "error": "Multiple document processing requires premium subscription",
  "code": "PREMIUM_FEATURE_REQUIRED",
  "statusCode": 403
}

Solution: Upgrade to premium plan or process documents individually.

Quota Errors

Quota Exceeded

{
  "error": "Monthly page quota exceeded",
  "code": "QUOTA_EXCEEDED",
  "statusCode": 403,
  "details": {
    "currentUsage": 1000,
    "limit": 1000,
    "renewsAt": "2025-06-01T00:00:00Z"
  }
}

Solution: Wait for quota renewal or upgrade your plan.

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429,
  "details": {
    "retryAfter": 3600
  }
}

Solution: Wait before making another request or implement exponential backoff.

Getting Help

If you encounter an error not covered in this guide:

1. Check the error code and message
2. Verify your request format
3. Try the request again
4. Contact support with the full error response

Remember to never include sensitive information like API keys when sharing error messages for support.