Useful API Diagnostics Begin With the Error Body

An AI request fails, and the application reports only “request failed.” That message discards the evidence needed to distinguish an expired credential from a malformed request, a capacity limit, or an interrupted stream. The useful explanation often sits in the response body. Reading it carefully starts with preserving the response, then separating facts from assumptions.

First, preserve the response before interpreting it

Start at the boundary where your application receives the HTTP response or catches an SDK exception. Preserve the status, response headers, and available body together. Record the request time and the requested model as well. These details describe one event; collecting them separately makes accidental mismatches more likely.

Some response interfaces let you consume the body only once. Read it deliberately, retaining a bounded copy when appropriate. Avoid dumping everything into production logs: error bodies can echo prompts, submitted values, or account details. Redact sensitive content and restrict access to diagnostic records.

Next, identify the format before extracting fields

Check the response content type, but treat it as a clue rather than a guarantee. A JSON response may contain a structured error object. A gateway failure may arrive as plain text or an HTML page. An empty body is also possible. Attempting JSON parsing unconditionally can replace the original failure with a misleading parser exception.

If parsing succeeds, inspect the actual structure before looking for familiar fields. Providers use different names and nesting for messages, categories, codes, and request identifiers. Keep the original status alongside the extracted message, and preserve a safely truncated text fallback when structured parsing fails.

Then, combine the status with the explanation

The HTTP status narrows the investigation; the body usually supplies the next action. An authentication failure may indicate a missing credential, while a permission failure may concern access to a particular resource. A request validation error may identify an unsupported parameter or an input limit. Read that detail before changing unrelated settings.

A rate limit response deserves the same care. It can reflect request frequency, token throughput, or another provider limit. Inspect any retry guidance in the headers and body. Server errors can justify retrying, but neither a status nor a reassuring message proves that repeating the request will succeed.

SDK exceptions and streams need separate inspection

If you use an SDK, inspect its documented exception properties. Depending on the library and version, the exception may expose a status, parsed body, headers, or underlying response. The short message printed by a terminal is often only a summary. Avoid assuming that every SDK preserves the same fields.

Streaming adds another failure point. A successful initial HTTP status establishes the stream, but an error can still arrive in a later event, or the connection can end unexpectedly. Track whether output began, whether an explicit error event arrived, and whether the stream completed normally. Keep partial output distinguishable from a completed answer.

Trace each failure across the relay boundary

For requests through BestRelay, preserve identifiers exposed by the relay and upstream provider when available. BestRelay forwards each request to the official model named in it without substitution. Its coverage includes Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, and Grok. A failure still needs evidence to locate its origin across the client, relay, and provider.

The same approach applies when using BestRelay with Claude Code, Codex, Gemini CLI, or an OpenAI SDK. If a tool displays only a short error, use its supported diagnostic facilities to recover more context. Share sanitized identifiers and timestamps with support rather than exposing credentials or an entire private conversation.

Choose the next action from the evidence

Correct validation and access problems before retrying. For transient failures, use bounded retries with increasing delays and respect explicit retry guidance. An interrupted response leaves uncertainty about completed work and usage, so check available usage records before assuming the attempt cost nothing. BestRelay bills pay as you go from provider-reported token counts, with cache reads and writes priced separately.

Create a BestRelay account to try this workflow with your own requests. Members also earn referral commission when people they invite top up. Keep operational decisions grounded in the captured error: the goal is a specific correction, a justified retry, or a support report containing enough evidence to investigate.