fraud agent tool call failed when transaction history api returned 500
Keeps reviews alive through transaction-history API 500s with bounded retries, circuit breakers, and a defined degraded mode. Use when the agent's tool call throws on server errors. Not for 4xx client errors or bad queries.
TL;DR
The transaction history API returns 500 and the agent's tool call throws, aborting the review. Fix: retry server errors with backoff, put a circuit breaker in front of the API, and define a degraded mode where the review completes with cached history or skips enrichment and is marked partial. A dependency being down should degrade the review, not kill it.
fraud agent tool call failed when transaction history api returned 500Use this when
- Tool calls throw on 500s from the history API across different queries.
- Reviews abort instead of completing during API incidents.
- One flaky dependency takes down the whole review pipeline.
Not for this skill when
- The API returns 4xx. That is a bad request, not a server failure.
- The query itself is malformed. Fix the query.
Steps
- Confirm the failure is server-side: 500s across different queries, not one bad request. Verify: the status codes are 5xx, not 4xx.
- Retry with exponential backoff and jitter, capped at three to five attempts. Verify: a brief outage is absorbed without failing the review.
- Add a circuit breaker: after repeated 500s, stop calling for a window and fail fast into degraded mode. Verify: the breaker opens and the API gets breathing room.
- Define degraded mode: use cached history with a staleness note, or skip enrichment and mark the review partial. Verify: reviews complete with the limitation recorded.
- Alert on sustained 500s with the error rate and the affected window. Verify: the owning team gets paged, not just the agent logs.
Variant phrasings
transaction history api 500
Common phrasing.
history api server error agent
Server-focused search.
tool call failed 500 history
Tool-focused phrasing.
500 error on history lookup
Lookup-focused phrasing.
Compatibility: any history or ledger API; the retry and breaker pattern is transport-level and framework-free.
Why it happens
The tool call was written assuming the API is always up. Transient 500s are normal in distributed systems, so the agent needs the same resilience any service client has. Treat the history API like any other flaky dependency: retries, breakers, and a degraded path.
Edge cases / pitfalls
- Degraded reviews must be re-enriched when the API recovers: queue them for a backfill pass, or partial becomes permanent.
- Cached history needs a staleness bound; ancient cache is worse than no cache.
- Distinguish 500 from 429: rate limits need slower retries honoring Retry-After, not the same backoff.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_Bim8bGqvQzl-a8UsI3EpOw