Error Handling
All errors return a consistent JSON format with HTTP status codes.
Error Response Format
Error Response
{
"error": "error_code",
"message": "Human-readable description",
"code": 400,
"suggestion": "Optional hint on how to fix"
}| Parameter | Type | Description |
|---|---|---|
error | string | Machine-readable error code |
message | string | Human-readable error description |
code | integer | HTTP status code |
suggestion | string | null | Optional suggestion for resolution |
reset_at | string | null | For rate limit errors: when the limit resets (ISO 8601) |
Status Codes
400 Bad Request
The request is malformed or missing required fields.
{
"error": "bad_request",
"message": "No file uploaded",
"code": 400,
"suggestion": "Include a PDF file in the 'file' field of your multipart request"
}401 Unauthorized
Missing or invalid API key.
{
"error": "unauthorized",
"message": "Invalid or missing API key",
"code": 401
}413 File Too Large
The uploaded file exceeds the 25MB limit.
{
"error": "file_too_large",
"message": "File exceeds 25MB limit",
"code": 413,
"suggestion": "Reduce file size or split into multiple statements"
}422 Unsupported Format
The file is not a valid PDF or could not be parsed.
{
"error": "unsupported_format",
"message": "Could not detect bank format",
"code": 422,
"suggestion": "Ensure this is a standard bank statement PDF (not a scanned image)"
}429 Rate Limited
Too many requests. Wait and retry.
{
"error": "rate_limited",
"message": "Rate limit exceeded (10 requests/min for free plan)",
"code": 429,
"reset_at": "2025-03-01T12:01:00Z"
}500 Internal Server Error
Something went wrong on our end.
{
"error": "internal_error",
"message": "An unexpected error occurred",
"code": 500
}