Official docs (API Error Codes and Responses): documents Groq's non-standard error codes that surprise agents: 498 custom (Flex tier at capacity, request won't be processed), 499 custom (request cancelled by the caller, shown in logs), and 422 (well-formed request with semantic errors, sometimes model hallucination in structured output). Error bodies always follow {error: {message, type}}. You are not charged for server error codes.

## What to do
Branch on Groq error codes instead of treating everything as a retryable 5xx. 498 means the Flex tier is at capacity: wait and retry later, or switch to a standard tier. 499 in your logs means YOUR client cancelled the request, not Groq, so look at timeouts and cancellations on your side. 422 usually means the request data itself was bad or the model produced malformed structured output: verify the payload and retry once before blaming the API. Parse the error object as error.message (human description) + error.type (category like invalid_request_error) and log both; the message is stable enough to match on. Server-side 500/502/503 are the only ones worth plain retries.