Error Codes

API error codes and troubleshooting

Common error codes and solutions.

HTTP Status Codes

200 - Success
201 - Resource created
202 - Accepted (parse request created and queued for async processing)
400 - Bad request
401 - Unauthorized (invalid API key)
402 - Payment required (insufficient credits)
404 - Resource not found
413 - Payload too large
429 - Too many requests
500 - Server error
501 - Not Implemented (prompt check level not available)

Error Response Format

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "remaining_balance": 0
}

Checks, validation, and job status

Text validation failures and prompt check detections are not API errors. The job finishes with status completed, includes a checks object describing what was found, and sets result, ai_features, and matching to null when the document does not pass those checks.

Only system-level failures (extraction, OCR, parse) produce status failed and the error response format described above. Matching failure after parse success is returned as partial success: status: completed with matching.status: "failed".

Common Errors

INVALID_API_KEY

API key is missing, invalid, or revoked.

Solution: Check your API key and ensure it's active.

INSUFFICIENT_CREDITS

Not enough credits to process request.

Solution: Purchase credits from your dashboard.

FILE_TOO_LARGE

File exceeds 8-page limit.

Solution: Split the document or upgrade your tier (contact support).

INVALID_FILE_FORMAT

Unsupported file type.

Solution: Use PDF, DOCX, TXT, JPG, or PNG files.

OCR_FAILED

Unable to extract text from image or scanned PDF.

Solution: Try a higher OCR tier (standard or premium) or provide a clearer image.

RATE_LIMIT_EXCEEDED

Too many requests in short period.

Solution: Wait before retrying. Check X-RateLimit-Reset header.

PARSE_TIMEOUT

Processing took longer than allowed.

Solution: Retry the request. If persistent, contact support.

MODEL_UNAVAILABLE

Selected AI model temporarily unavailable.

Solution: Retry with same model or switch to another model.

NOT_IMPLEMENTED

The requested prompt check level (advanced or professional) is not yet available.

Solution: Use 'basic' level or disable prompt check.

INVALID_INPUT (matching)

Common matching validation failures:

Missing input.job_description when matching is enabled
input.job_description shorter than 100 characters
input.job_description longer than 30,000 characters
steps.matching.top_skills outside 1–10

Solution: Provide a valid JD length and valid matching options.

Retrying Requests

For transient errors (5xx, timeouts), implement exponential backoff:

async function parseWithRetry(input, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await parse(input);
    } catch (error) {
      if (error.status >= 500 && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Need Help?

If you encounter persistent errors:

Check the Status Page
Review your recent API calls in the dashboard
Contact support with your request_id

Search documentation