Error Reference
Complete reference of HirePlus API error codes and troubleshooting.
Error Reference
All API errors return a JSON response with an error field describing the issue.
Error Response Format
{
"error": "Description of the error"
}HTTP Status Codes
400 Bad Request
The request was malformed or missing required fields.
| Error Message | Cause | Fix |
|---|---|---|
Missing required field: file | No file attached to the request | Include a file in the file form field |
File too large. Maximum size is 10MB. | Uploaded file exceeds 10MB | Compress or split the file |
Unsupported file type. Use PDF, DOCX, or TXT. | File is not a supported format | Convert to PDF, DOCX, or TXT |
401 Unauthorized
Authentication failed.
| Error Message | Cause | Fix |
|---|---|---|
Invalid or expired API key | Missing, revoked, or incorrect API key | Check your API key in Dashboard → Settings → API Keys |
404 Not Found
The requested resource does not exist.
| Error Message | Cause | Fix |
|---|---|---|
Analysis not found | The analysis ID doesn't exist or belongs to another account | Verify the analysis ID; ensure you're using the correct API key |
429 Too Many Requests
Rate or usage limit exceeded.
| Error Message | Cause | Fix |
|---|---|---|
Rate limit exceeded. Max 100 requests per minute. | Too many requests in a short period | Wait and retry with exponential backoff |
Monthly analysis limit reached | Plan quota exhausted | Upgrade your plan or wait for the next billing period |
500 Internal Server Error
An unexpected error occurred on the server.
| Error Message | Cause | Fix |
|---|---|---|
Internal server error | Server-side processing failure | Retry the request; contact support if persistent |
Troubleshooting
Common Issues
"Invalid or expired API key"
- Ensure the key is in the
x-api-keyheader (notAuthorization) - Check that the key hasn't been revoked in the Dashboard
- Verify there are no trailing spaces or newlines in the key
"File too large"
- PDF files with embedded images can be large — try re-exporting with compression
- Remove unnecessary pages from multi-page documents
"Unsupported file type"
- Google Docs: Export as PDF before uploading
- Pages files: Export as PDF or DOCX
- Images of resumes: Convert to text first (we don't support image-based CVs)