BillerApi/Docs
Sign inGet started
Navigation

Feedback errors

Catalog of FEEDBACK_* error codes returned by the POST /v1/scraping-runs/:run_id/feedback endpoint. Each entry covers the cause, what to do, and an example response body.

Jump to

404FEEDBACK_RUN_NOT_FOUND

Run does not exist

Cause

No scraping run with that run_id exists. Either the run_id is malformed, was never persisted (the agent crashed before flushing the trace), or you're passing a stale identifier.

What to do

Confirm the run_id came verbatim from a real scraping flow. Don't expose this error to end users — surface a generic "we couldn't find that report" message and log the run_id for internal investigation.

Example response

JSON
{
  "error_code": "FEEDBACK_RUN_NOT_FOUND",
  "error_type": "not_found",
  "error_message": "No scraping run found with run_id=run_abc123",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}
403FEEDBACK_RUN_NOT_OWNED

Run belongs to a different client

Cause

The run_id exists but its client_id does not match the credentials on the request. This is a tenant isolation check — clients can only file feedback for their own runs.

What to do

Audit your run_id storage. You should never see this in normal operation. If it happens, you have a client_id confusion bug in your application — likely cross-contamination between two BillerAPI integrations.

Example response

JSON
{
  "error_code": "FEEDBACK_RUN_NOT_OWNED",
  "error_type": "forbidden",
  "error_message": "Run run_abc123 belongs to a different client",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}
409FEEDBACK_ALREADY_SUBMITTED

Feedback already exists for this run

Cause

A different Idempotency-Key already submitted feedback for the same (client_id, run_id). Each scraping run accepts exactly one feedback submission.

What to do

Treat this as a successful idempotent outcome — feedback was recorded, just from an earlier call. Surface "report already received" to the user. To retry safely on the SAME submission, re-send with the SAME Idempotency-Key (returns 201 with already_existed: true). Use a NEW key only for a NEW submission.

Example response

JSON
{
  "error_code": "FEEDBACK_ALREADY_SUBMITTED",
  "error_type": "conflict",
  "error_message": "Feedback already submitted for run run_abc123 (different idempotency key)",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}
410FEEDBACK_RUN_EXPIRED

Run is older than 30 days

Cause

Feedback windows are bounded to 30 days from the run's creation. Older runs don't accept new feedback — the agent self-improvement pipeline trains on recent signal and lets older runs age out of the brain.

What to do

Don't retry. Surface "this report is too old to file" if user-facing, or drop on the floor if this is from a backfill job. Don't hold onto run_ids past 30 days for the purpose of late-filing feedback.

Example response

JSON
{
  "error_code": "FEEDBACK_RUN_EXPIRED",
  "error_type": "gone",
  "error_message": "Run run_abc123 is older than the 30-day feedback window",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}
422FEEDBACK_INVALID_CATEGORY

Signal value is not allowed

Cause

The signal field is missing, empty, or not one of: succeeded, login_failed, bill_missing, data_incorrect. (The error code name says CATEGORY for legacy reasons; the field is signal.)

What to do

Fix client-side validation. Use a typed enum in your SDK so this can't happen at runtime. The full list is on the API reference page.

Example response

JSON
{
  "error_code": "FEEDBACK_INVALID_CATEGORY",
  "error_type": "validation",
  "error_message": "signal must be one of: succeeded, login_failed, bill_missing, data_incorrect",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}
429FEEDBACK_RATE_LIMITED

Too many submissions for this (client × biller) tuple

Cause

You exceeded 100 submissions per hour per (client_id, biller_id) tuple. The limit is keyed on the biller — separate billers consume separate quotas. Usually benign and self-resolves with backoff.

What to do

Back off (a minute or two is usually enough). If many users are reporting on the same biller (often the sign of a real degradation), queue submissions at your edge. Don't hot-loop without backoff.

Example response

JSON
{
  "error_code": "FEEDBACK_RATE_LIMITED",
  "error_type": "rate_limited",
  "error_message": "Too many feedback submissions for (client, biller_verizon)",
  "request_id": "req_abc123",
  "documentation_url": "https://docs.billerapi.com/docs/concepts/errors/feedback-errors"
}

Related