Code against error.code, log request_id, and use the HTTP status only as the broad failure class.
{
"error": {
"type": "invalid_request_error",
"code": "invalid_query_parameter",
"message": "A query parameter is invalid.",
"param": "fields",
"request_id": "req_01JAZ…"
}
}Retry 429, 502, 503 and 504 with Retry-After and bounded jitter. Do not retry malformed input, missing scopes, an idempotency-key conflict or a genuine entity revision conflict without changing the request.
Record request_id, the endpoint, status and error code. Never log Authorization, API keys, webhook secrets or full sensitive bodies.
Each generated endpoint lists the exact errors it can return →