Error Codes

When a request fails, the API returns a JSON error response with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

The code field is stable and safe to match against in your application logic. The message field may change over time and is intended for logging and debugging.

Error Code Reference

Code	HTTP Status	Description	Retryable	Resolution
UNAUTHORIZED	401	Missing, invalid, or expired authentication token	No	Check your API key is valid and not expired
KEY_EXPIRED	401	API key has passed its expiration date	No	Create a new API key in the dashboard or via the API
FORBIDDEN	403	Authenticated but not authorized for this resource	No	You can only access your own resources
NOT_FOUND	404	Requested resource does not exist	No	Verify the resource ID is correct
VALIDATION_ERROR	400	Request body failed schema validation	No	Check required fields and data types match the schema
INVALID_MIME_TYPE	400	Uploaded file has an unsupported MIME type	No	Use a supported file type (PDF or DOCX)
FILE_TOO_LARGE	400	Uploaded file exceeds the 10 MB size limit	No	Reduce file size or split into smaller documents
MAX_KEYS_REACHED	400	Maximum of 10 active API keys reached	No	Revoke unused keys before creating new ones
USAGE_LIMIT_EXCEEDED	429	Monthly extraction limit reached	No	Upgrade your plan or wait for the next billing period
INTERNAL_ERROR	500	Unexpected server error	Yes	Retry with exponential backoff. If persistent, contact support
NOT_CONFIGURED	501	Required server-side service is not configured	No	Contact support -- this indicates a server configuration issue
EXTRACTION_FAILED	502	AI extraction processing failed	Yes	Retry -- may be a transient issue. Check that the PDF is valid and readable
EXTRACTION_PARSE_ERROR	502	AI returned a response that could not be parsed as JSON	Yes	Retry -- the AI may produce valid output on a subsequent attempt

Retryable Errors

Only the following error codes should be retried:

• INTERNAL_ERROR -- An unexpected failure on the server side.
• EXTRACTION_FAILED -- The AI extraction process failed, often due to transient issues.
• EXTRACTION_PARSE_ERROR -- The AI returned malformed output that could not be parsed.

When retrying, use exponential backoff starting at 1 second, with a maximum of 3 retries:

Attempt	Delay
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds

If the request still fails after 3 retries, log the error and surface it to the user or your monitoring system.

For a complete guide on implementing retry logic, see Error Handling.

HTTP Status Code Summary

Status	Meaning
200	Success -- the request completed successfully
400	Bad Request -- validation error, invalid file type, file too large, or key limit reached
401	Unauthorized -- authentication failed (missing, invalid, or expired token)
403	Forbidden -- authenticated but not authorized for the requested resource
404	Not Found -- the requested resource does not exist
429	Too Many Requests -- monthly extraction usage limit exceeded
500	Internal Server Error -- unexpected failure on the server side
501	Not Implemented -- a required server-side service is not configured
502	Bad Gateway -- AI extraction or parsing failed