Read the whole response
For an unsuccessful status, retain the HTTP code, headers, error body, and request id after removing secrets. They distinguish an invalid request from an access rejection or temporary issue.
Do not expose a raw service response as the only user message: explain the action while retaining diagnostic detail for an operator.
Inspect a failed response
bash
curl --include --request POST https://cicora.ai/api/v1/chat/completions \
--header "Authorization: Bearer $CICORA_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"model":"openai/gpt-5.6-sol","messages":[]}'Classify the failure
- 4xx usually requires correcting a key, input data, or access.
- 429 requires respecting the limit window and avoiding an aggressive retry.
- 5xx and network failures call for bounded retries with exponential backoff and jitter.
Retry safely
Retry only transient failures and only if the operation is idempotent in your product. For generation, keep a client request id to prevent double charging or a duplicate artifact.
In streaming, distinguish an error before the first delta from a break after partial output: the latter cannot be silently replaced with a new response.