$2 Budget: Handle 401, 402 and 429 Without Waste

01 / Start with a $2 spending limit and three error rules

Suppose you have $2 available for an AI coding experiment. That is your example spending limit, not a promise about how many requests it buys. Your model, input length, output length, and cache usage determine the bill. A client that repeats every failed request can waste time and create avoidable spending risk.

You need three rules before sending your first request: stop on 401, investigate 402, and wait before retrying 429. Keep the original prompt available so the user can try again after fixing the problem.

02 / 401: Fix the key before sending another request

A 401 response means the server could not authenticate your request. Common causes include a missing key, an invalid or revoked key, or an incorrectly formed authorization header. Repeating the same request with the same credentials usually changes nothing.

For an OpenAI-compatible client, check these items in order:

• ■ Confirm that the API key is present in the environment used by the running application.
• ■ Check that the request sends Authorization: Bearer followed by the key, without extra quotation marks or spaces inside it.
• ■ Verify that the key and API base belong to the same service.
• ■ Restart the application after changing an environment variable if it reads configuration only at startup.

For CheapRelay’s OpenAI-compatible routes, configure the SDK base URL as https://api.cheapapirelay.com/v1. Gemini native routes use /v1beta, so check the client’s protocol as well as its key. Keep keys out of screenshots, logs, and browser code shipped to users.

Show a useful message: “Authentication failed. Check your API key and endpoint, then try again.” Disable automatic retries for this error. If your application uses expiring access tokens, a single supported refresh attempt may be appropriate; ordinary API keys need a configuration fix.

03 / 402: Pause spending and inspect the payment message

The meaning of 402 depends on the API. It can indicate insufficient credit, a billing restriction, or another payment requirement. Read the service’s error message and documentation before deciding that a top-up is the answer.

Stop automatic retries and show: “The service reported a payment issue. Check your balance and billing details.” Preserve the task, but require an explicit retry after the issue is resolved. Never automatically add funds just because a request failed.

CheapRelay bills per real token, including cache reads and writes, with no monthly fee or subscription. That makes usage tracking relevant even for a small experiment. Set a local spending threshold below your available balance to leave room for delayed accounting and requests already in flight. A local estimate is a guardrail, not a guaranteed billing cap.

04 / 429: Allow two retries, with a wait between attempts

A 429 response usually signals a rate or quota limit. Check the error details: a temporary request limit may clear after a pause, while an exhausted quota may require account action.

For temporary limits, use this small retry policy:

• ■ Allow at most two retries after the initial attempt: three attempts total.
• ■ If Retry-After is present, parse its delay in seconds or its HTTP date and wait at least that long.
• ■ Without Retry-After, wait one second before the first retry and two seconds before the second, adding a small random delay to each.
• ■ If the required wait exceeds your chosen 30-second interactive limit, stop and tell the user when to try again.

Start with one request in flight. Check your SDK’s built-in retry settings so your own loop does not multiply its attempts. Do not assume every 429 attempt is free; billing behavior depends on the service and whether work occurred.

05 / Test the failure paths before spending the $2

Use mocked responses to test all three cases without making paid model calls. Confirm that 401 and 402 stop immediately, 429 respects Retry-After, and cancellation prevents another attempt. Log the status, attempt count, and request identifier when available. Avoid logging keys or full prompts.

Sign up for CheapRelay when you are ready to test this policy against a live API. Begin with a short prompt and a small output limit, then compare reported usage with your spending estimate before increasing traffic.