Error code reference
Every stable error_code BillerAPI returns, with its HTTP status, category, and a dedicated page (problem / cause / fix / example). Each error response also links here via its docs_url. The list is additive-only — codes are never removed or renamed.
General
| Code | Status | Type | Summary |
|---|---|---|---|
| INTERNAL_ERROR | 500 | api_error | An unexpected error occurred on our end. |
| VALIDATION_ERROR | 400 | invalid_request | One or more request fields are invalid. |
| NOT_FOUND | 404 | invalid_request | The requested resource does not exist. |
| CONFLICT | 409 | invalid_request | The request conflicts with the current resource state. |
| INVALID_CURSOR | 400 | invalid_request | The pagination cursor is malformed or stale. |
| IDEMPOTENCY_KEY_MISMATCH | 409 | invalid_request | The Idempotency-Key was reused with a different body. |
| RATE_LIMITED | 429 | rate_limit | You have exceeded the allowed request rate. |
| SERVICE_UNAVAILABLE | 503 | upstream | An upstream dependency is temporarily unavailable. |
Authentication
| Code | Status | Type | Summary |
|---|---|---|---|
| UNAUTHORIZED | 401 | auth | Authentication failed or is missing. |
| FORBIDDEN | 403 | auth | Authenticated, but not authorized for this resource. |
| CLIENT_ID_MISMATCH | 403 | auth | The supplied client_id does not match your session. |
| NEEDS_RESIGNIN | 401 | auth | No authenticated client context was resolved. |
Bills & statements
| Code | Status | Type | Summary |
|---|---|---|---|
| BILL_NOT_FOUND | 404 | invalid_request | No bill exists with that id. |
| ACCOUNT_LINK_NOT_FOUND | 404 | invalid_request | The account link does not exist. |
| STATEMENT_NOT_EXTRACTED | 425 | invalid_request | The statement has not been extracted yet. |
| EXTRACTION_FAILED | 503 | upstream | Statement extraction failed upstream. |
| EXTRACTION_UNSUPPORTED_FOR_BILLER | 422 | invalid_request | This biller does not support statement extraction. |
| STATEMENT_TOO_LARGE | 413 | upstream | The statement exceeds the size limit. |
Links & Connect
| Code | Status | Type | Summary |
|---|---|---|---|
| LINK_NOT_FOUND | 404 | invalid_request | No link exists with that id. |
| LINK_TOKEN_NOT_FOUND | 404 | invalid_request | The link token is unknown or expired. |
| BACKGROUND_NOT_ELIGIBLE | 409 | invalid_request | The link token cannot be backgrounded now. |
| UPDATE_BILLER_MISMATCH | 409 | invalid_request | The update token targets a different biller. |
| INVALID_UPDATE_REASON | 400 | invalid_request | The update reason is not a recognized value. |
| LINK_UPDATE_FORBIDDEN | 403 | auth | The update token belongs to a different client. |
| REDIRECT_URI_NOT_REGISTERED | 400 | invalid_request | The redirect_uri is not in your registered allowlist. |
Billers
| Code | Status | Type | Summary |
|---|---|---|---|
| BILLER_NOT_FOUND | 404 | invalid_request | No biller exists with that id. |
| BILLER_UNSUPPORTED | 422 | invalid_request | This biller cannot be automated. |
Payments
| Code | Status | Type | Summary |
|---|---|---|---|
| PAYMENT_EXECUTION_NOT_AVAILABLE | 501 | upstream | Payment execution is not yet available. |
Feedback
| Code | Status | Type | Summary |
|---|---|---|---|
| FEEDBACK_RUN_NOT_FOUND | 404 | invalid_request | The referenced resource does not exist. |
| FEEDBACK_RUN_NOT_OWNED | 403 | auth | The referenced resource belongs to another client. |
| FEEDBACK_RUN_EXPIRED | 410 | invalid_request | The feedback window has closed. |
| FEEDBACK_INVALID_CATEGORY | 422 | invalid_request | The category is not valid for this resource type. |
| FEEDBACK_INVALID_SIGNAL | 400 | invalid_request | The signal is not valid for the resource_type. |
| FEEDBACK_ALREADY_SUBMITTED | 409 | invalid_request | Feedback was already submitted for this resource. |
| FEEDBACK_RATE_LIMITED | 429 | rate_limit | Too many feedback submissions. |
Messaging
| Code | Status | Type | Summary |
|---|---|---|---|
| MESSAGING_CONSENT_NOT_GRANTED | 403 | invalid_request | The customer has not granted messaging consent. |
| MESSAGING_LIVE_ACCESS_REQUIRED | 403 | auth | Messaging requires production (live) access. |
| MESSAGING_CONTENT_FLAGGED | 422 | invalid_request | The message content was flagged. |
| MESSAGING_RATE_LIMITED | 429 | rate_limit | Messaging rate limit exceeded. |
| MESSAGING_SUPPRESSED | 200 | invalid_request | The recipient is suppressed; message not sent. |
| MESSAGING_AUP_NOT_ACCEPTED | 428 | invalid_request | The messaging Acceptable Use Policy is not accepted. |
| MESSAGING_AUP_REACCEPT_REQUIRED | 412 | invalid_request | The messaging AUP must be re-accepted. |
| MESSAGING_INVALID_PAYLOAD | 400 | invalid_request | The message payload is malformed. |
| MESSAGING_INVALID_CATEGORY | 400 | invalid_request | The message category is not recognized. |
| MESSAGING_PERSIST_FAILED | 503 | upstream | A transient error prevented recording the message. |
| MESSAGING_INTERNAL_ERROR | 500 | upstream | An unexpected messaging error occurred. |
| MESSAGING_NOT_FOUND | 404 | invalid_request | The referenced message or thread does not exist. |
Related
- Error handling — the error envelope shape and parsing strategy
- Rate limits — backoff + retry-after semantics
Was this page helpful?