Error Handling

Learn how to handle errors and troubleshoot common issues.

Error Response Format

When an error occurs, the API returns a JSON response with details about the error:

Error Response

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "API key not found or has been revoked.",
    "hint": "Check your API key or generate a new one from the dashboard."
  }
}

HTTP Status Codes

Status	Meaning
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Missing or invalid API key
413	Payload Too Large - File exceeds maximum size (50MB)
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Common Error Codes

Code	Description	Solution
`AUTHENTICATION_REQUIRED`	No API key provided	Add Authorization header
`AUTHENTICATION_FAILED`	Invalid or revoked API key	Check key or generate new one
`INVALID_PDF`	File is not a valid PDF	Ensure file is a valid PDF
`FILE_TOO_LARGE`	File exceeds 50MB limit	Compress or split the file
`RATE_LIMIT_EXCEEDED`	Monthly limit reached	Wait for reset or upgrade
`API_KEY_WRONG_DOMAIN`	API key used on main domain	Use api.morphopdf.com

Best Practices

1.Always check the status code - Don't assume success, check the HTTP status code first.
2.Parse error responses - The error object contains useful debugging information.
3.Implement retries for 5xx errors - Server errors are usually temporary, retry with exponential backoff.
4.Don't retry 4xx errors - Client errors require fixing the request before retrying.