Error Codes

ExtractForm uses standard HTTP status codes. Error responses include a message and optional details.

HTTP status codes

Status	Meaning	Common causes
400	Bad Request	Invalid body, missing required field, unsupported file type
401	Unauthorized	Missing, expired, or invalid token/API key
403	Forbidden	Insufficient role (e.g. ADMIN-only route)
404	Not Found	Resource does not exist or belongs to another user
409	Conflict	Duplicate resource (e.g. idempotency key reuse with different payload)
413	Payload Too Large	File exceeds MAX_FILE_SIZE
429	Too Many Requests	Rate limit exceeded (auth endpoints throttled)
500	Internal Server Error	Unexpected server error — retry with backoff

Authentication errors

Scenario	Status	Fix
No Authorization header	401	Add Authorization: Bearer <token>
Expired access token	401	Call POST /api/auth/refresh
Revoked or expired API key	401	Create a new key or use a valid JWT
Invalid credentials on login	401	Check email and password

Job errors

When a job reaches FAILED status, check errorMessage and errorCode on the job object:

curl http://localhost:4000/api/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Common failure reasons:

• Unsupported or corrupted file format
• Schema not found or deleted
• AI provider timeout or rate limit
• Document parsing failure

Use POST /api/jobs/:id/restart to retry a failed job.

Webhook delivery errors

Webhook deliveries retry with exponential backoff. Check delivery logs:

curl "http://localhost:4000/api/webhooks/WEBHOOK_ID/deliveries?status=DEAD" \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoints are auto-disabled after WEBHOOK_AUTO_DISABLE_THRESHOLD consecutive dead deliveries (default 5).

Integration errors

Scenario	Fix
OAuth token expired	Disconnect and reconnect the integration
Dropbox permission denied	Enable required scopes in Dropbox App Console
S3 access denied	Verify access key, bucket, and region
File not found in remote storage	Confirm fileId and folder path

Validation errors

400 responses from validation include details about which field failed:

{
  "statusCode": 400,
  "message": ["email must be an email", "password must be longer than or equal to 6 characters"],
  "error": "Bad Request"
}