Feedback errors
Catalog of FEEDBACK_* error codes returned by the POST /v1/feedback endpoint. Each entry covers the cause, what to do, and an example response body.
Jump to
FEEDBACK_INVALID_SIGNALSignal is not valid for the resource (or key missing)
Cause
The signal is not one of the values allowed for the request's resource_type, the resource_type is unsupported, or the required idempotency_key is missing. The valid signal set per resource_type is on the API reference page.
What to do
Fix client-side validation. Use a typed enum keyed on resource_type in your SDK so an invalid pairing can't happen at runtime, and always send an idempotency_key.
Example response
{
"error_code": "FEEDBACK_INVALID_SIGNAL",
"error_type": "invalid_request",
"error_message": "Signal 'wrong_account' is not valid for resource_type 'bill'.",
"hint": "Use a typed enum keyed on resource_type in your SDK, and always send an idempotency_key.",
"docs_url": "https://docs.billerapi.com/errors/FEEDBACK_INVALID_SIGNAL",
"request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34"
}FEEDBACK_RUN_NOT_FOUNDResource missing or not owned
Cause
No resource with that resource_id belongs to your client. Missing and not-owned are deliberately collapsed into one response — there is no cross-tenant existence oracle. (Note: an unknown/aged-out producing run is NOT this error; that soft-accepts with 202 and attributable:false.)
What to do
Confirm the resource_id came verbatim from a resource your client owns (a bill id you received, or an account-connection id). Don't expose this to end users — surface a generic "we couldn't find that" message and log for investigation.
Example response
{
"error_code": "FEEDBACK_RUN_NOT_FOUND",
"error_type": "invalid_request",
"error_message": "No bill with id 'bill_abc123' belongs to your client.",
"hint": "Verify the referenced resource id from a recent response.",
"docs_url": "https://docs.billerapi.com/errors/FEEDBACK_RUN_NOT_FOUND",
"request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34"
}FEEDBACK_ALREADY_SUBMITTEDFeedback already exists for this resource
Cause
A different idempotency_key already submitted feedback for this resource. To retry the SAME submission, reuse the original key (returns 202 with already_existed:true); a new key for the same resource conflicts.
What to do
Treat as a successful idempotent outcome — feedback was already recorded. Surface "report already received" to the user. Reuse the original idempotency_key to retry safely; use a new key only for a genuinely new submission.
Example response
{
"error_code": "FEEDBACK_ALREADY_SUBMITTED",
"error_type": "invalid_request",
"error_message": "Feedback for 'bill_abc123' was already submitted under a different idempotency_key.",
"hint": "Reuse the original idempotency_key to make the submission idempotent.",
"docs_url": "https://docs.billerapi.com/errors/FEEDBACK_ALREADY_SUBMITTED",
"request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34"
}PAYMENT_EXECUTION_NOT_AVAILABLEPayment feedback is reserved
Cause
resource_type "payment" is registered but not yet available — payment execution is gated. The endpoint short-circuits before validating the signal.
What to do
Don't submit payment feedback yet. Use resource_type "bill" or "account_connection". This response is stable; you can treat it as "feature not enabled".
Example response
{
"error_code": "PAYMENT_EXECUTION_NOT_AVAILABLE",
"error_type": "upstream",
"error_message": "Feedback is not available for resource_type 'payment' yet.",
"hint": "Payment feedback is not available yet. Use resource_type 'bill' or 'account_connection'.",
"docs_url": "https://docs.billerapi.com/errors/PAYMENT_EXECUTION_NOT_AVAILABLE",
"request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34"
}FEEDBACK_RATE_LIMITEDToo many submissions
Cause
You exceeded 100 feedback submissions per hour for your client. Usually benign and self-resolves with backoff.
What to do
Back off (a minute or two is usually enough). If many users are reporting at once (often a sign of a real degradation), queue submissions at your edge. Don't hot-loop without backoff.
Example response
{
"error_code": "FEEDBACK_RATE_LIMITED",
"error_type": "rate_limit",
"error_message": "Too many feedback submissions; retry after the window resets.",
"hint": "Back off and retry after the window.",
"docs_url": "https://docs.billerapi.com/errors/FEEDBACK_RATE_LIMITED",
"request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34",
"retry_after": 30
}