Error Codes

All API errors return a consistent JSON structure with an error code and human-readable message.

Error Response Format

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

Error Code Reference

Client Errors (4xx)

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid input data (malformed JSON, invalid UUID, etc.)
FILE_REQUIRED	400	Upload endpoint called without a file
INVALID_FILE_TYPE	400	File MIME type not in allowed list (must be image/jpeg, image/png, or application/pdf)
INVALID_FORMAT	400	Export format must be docx or xlsx
NOT_READY	400	Document must be completed with OCR results before this operation
NO_FILE	400	No file stored for this document
QUERY_REQUIRED	400	Search endpoint called without q parameter
INVALID_TOKEN	400	Verification, reset, or confirmation token is invalid, expired, or already used
UNAUTHORIZED	401	Missing, invalid, or expired access token
INVALID_CREDENTIALS	401	Wrong email or password during login
ACCOUNT_DISABLED	403	User account has been deactivated
EMAIL_NOT_VERIFIED	403	Email address not yet verified (must verify before accessing the API)
DEVICE_NOT_CONFIRMED	403	New device requires email confirmation before login can proceed
DOCUMENT_NOT_FOUND	404	Document doesn't exist or belongs to a different user
EMAIL_TAKEN	409	Email address already registered
RATE_LIMITED	429	Too many requests; includes Retry-After header

HTTP Status Codes

Status	Meaning
200	Success
201	Created (registration)
202	Accepted (async email queued)
204	No Content (successful delete)
400	Bad Request (validation error)
401	Unauthorized (auth failure)
403	Forbidden (not verified, not confirmed, or disabled)
404	Not Found
409	Conflict (duplicate)
429	Rate Limited
500	Internal Server Error

Rate Limiting

When you receive a 429 response, check the Retry-After header for the number of seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait 15 seconds."
  }
}

Rate Limits by Endpoint

Endpoint	Limit
POST /v1/auth/register	5 per hour per IP
POST /v1/auth/login	3 free, then exponential backoff (15s, 30s, 60s, 300s)
POST /v1/auth/resend-verification	1 per minute, 5 per hour per email
POST /v1/auth/forgot-password	1 per minute, 5 per hour per email

Handling Errors

Best Practices

1. Always check the HTTP status code before parsing the response body
2. Parse the error.code field for programmatic error handling
3. Display error.message to users for human-readable feedback
4. Implement token refresh -- when you receive a 401, try refreshing the access token before re-authenticating
5. Respect rate limits -- implement exponential backoff when receiving 429 responses