01
Read the status, error code, and request ID together.
BrokenGPT returns typed JSON errors for public API failures and includes a request identifier where the route can provide one. Preserve that identifier in your logs and support report, but never include the bearer credential.
The HTTP status tells you the broad class. The error code provides the more specific cause. The message can help a person, but production control flow should not depend on exact prose.
ERROR ENVELOPE
{"error":{"message":"Invalid API key","type":"authentication_error","code":"invalid_api_key","param":null}}02
Map each status class to one bounded action.
| Status | Typical cause | Client action |
|---|---|---|
| 400 | Invalid JSON, field, context, or unsupported combination | Fix the request; do not retry unchanged |
| 401 | Missing or invalid API key | Replace the credential |
| 403 | Key lacks the required scope | Use or create a correctly scoped key |
| 404 | Unknown public model alias | Use broken-one from current docs |
| 409 | Idempotency key reused with a different body | Use a new key or the original body |
| 413 | Request body exceeds the route limit | Reduce or split the payload |
| 429 | Rate, key limit, budget, or credit exhaustion | Inspect the code; back off only when time can resolve it |
| 500-503 | Temporary service or accounting failure | Retry with jitter and a hard attempt limit |
03
Treat context errors as a sizing problem, not an outage.
The input plus an explicit output cap must fit inside the advertised context window. A large character count is not an exact token count, and tools or structured schemas also contribute to serialized input.
- Remove duplicated instructions and irrelevant history.
- Summarize or retrieve only the passages needed for the current turn.
- Lower the requested output cap when it is explicit.
- Use the token-count route for planning, then keep a margin for serialization differences.
04
Streaming failures need state-aware handling.
- Do not blindly replay a request after displaying partial output; a retry can duplicate user-visible work.
- Treat the terminal [DONE] marker and finish reason as completion signals.
- If the caller disconnects, cancel upstream work when your runtime supports it.
- For structured JSON, use a non-streamed request because validation happens before delivery.