One question can become an uncontrolled request tree
A person may ask for one comparison, but a planning model can search competitions, inspect several teams, request multiple date windows, and retry weak branches. Without controls, a single chat turn consumes a surprising portion of the monthly quota or collides with the per-minute limit. Prompt instructions alone are not a rate limiter.
Create a request budget in the orchestration layer. Count every attempted authenticated request, including retries and errors after authentication. Expose remaining budget to the planner, but enforce it in code. Coalesce identical in-flight requests and reuse validated results within the same workflow so parallel reasoning does not duplicate network work.
Recover from 429 without making the incident worse
When the API returns 429, read Retry-After and rate-limit headers. Pause that account’s queue rather than letting every worker retry independently. Add bounded jitter after the required wait to avoid synchronized bursts. A retry must also fit the user’s time budget; a background report can wait, while an interactive request may need a partial answer.
Monthly exhaustion is different from a short per-minute throttle. Waiting sixty seconds will not restore a depleted monthly allowance. Map the response into a typed condition that the agent can explain, preserve completed evidence, and offer a continuation plan. Never tell the model to change credentials or rotate keys as a way to evade an account-level limit.
max_attempts: 3
max_elapsed_seconds: 20
429: honor Retry-After, then add bounded jitter
401: do not retry
404: do not invent another ID
503: retry only while the elapsed budget remainsA handoff your agent can actually follow
Treat an AI agent as a planner and transformer, not as the database. Give it a narrow task, the exact resources it may call, the response fields it may quote, and a stop condition for missing data. Keep bearer credentials in the server-side tool implementation rather than in the prompt, transcript, browser, or generated source file.
The handoff below is deliberately operational. It asks for evidence before prose, makes uncertainty visible, and keeps the model inside the current football API contract. Adapt the output format to your product, but preserve the rules about stable IDs, UTC timestamps, freshness, and error handling.
Give this workflow a fixed request budget.
Before each tool call, check the remaining per-minute and monthly allowance.
On 429, honor Retry-After and retry only within the time and attempt budget.
If the budget expires, return partial evidence and a clear continuation point.What the human reviewer still owns
Automation can verify schemas and repeatable checks, but publication and product decisions still need a person. Review the selected competition, season, team, and match IDs; confirm that the time window matches the user’s question; and read the final answer against the retrieved JSON. A fluent explanation is not evidence that the underlying call was correct.
For time-sensitive football AI, record when the source was ingested and when the agent retrieved it. If the workflow cannot establish those timestamps, qualify the result instead of presenting it as current. The same rule applies to unavailable capabilities: do not quietly substitute fixtures or results for lineups, player statistics, odds, expected goals, injuries, or live events.
- Confirm every quoted fact appears in the retained API response.
- Exercise the empty, 401, 404, 429, and 503 paths before launch.
- Keep model interpretation separate from source facts in logs and user-facing output.
- Simulate several agents sharing one account so per-key concurrency cannot accidentally multiply the account-level allowance.
Continue with the contract, not a guess
Start with the public contract and coverage ledger, then move into implementation only when the capability you need is marked available. The related guide gives your next agent-first pattern without requiring an undocumented endpoint.