From 6e02d6dc8b11620328819372328b1e20017e1427 Mon Sep 17 00:00:00 2001 From: Charlie Gleason Date: Thu, 22 Oct 2026 17:35:40 -0700 Subject: [PATCH] [AI Gateway] Document Run exhausted-credit errors --- src/content/docs/ai-gateway/reference/troubleshooting.mdx | 8 ++++++++ src/content/docs/ai-gateway/usage/rest-api.mdx | 4 +++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/src/content/docs/ai-gateway/reference/troubleshooting.mdx b/src/content/docs/ai-gateway/reference/troubleshooting.mdx index 917efdb1de7..bf35e770d55 100644 --- a/src/content/docs/ai-gateway/reference/troubleshooting.mdx +++ b/src/content/docs/ai-gateway/reference/troubleshooting.mdx @@ -38,6 +38,14 @@ For troubleshooting Data Loss Prevention issues such as DLP not triggering or un ## Request failures +### Insufficient credits (`402`) + +When a [Run request](/ai-gateway/usage/rest-api/) uses Unified Billing, exhausted credits return HTTP `402` with `internalCode: 2021` in the error response. + +[Add credits](/ai-gateway/features/unified-billing/#load-credits) before retrying the request. Retrying without replenishing your balance does not resolve this error. + +A background run can also fail because credits are exhausted. An initial `202` response confirms acceptance, not successful completion. If you configured a webhook, check the `state` and `error` fields in its [payload](/ai-gateway/usage/rest-api/#webhook-payload) for the final outcome. + ### Requests timing out - Check if the upstream provider is experiencing issues diff --git a/src/content/docs/ai-gateway/usage/rest-api.mdx b/src/content/docs/ai-gateway/usage/rest-api.mdx index 0c7a8ea00a7..f7c5fb17c94 100644 --- a/src/content/docs/ai-gateway/usage/rest-api.mdx +++ b/src/content/docs/ai-gateway/usage/rest-api.mdx @@ -154,7 +154,7 @@ curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ }' ``` -A background request returns immediately while the model runs. The result is delivered to your webhook when the run completes. +An accepted background request returns HTTP `202` while the model runs. This confirms acceptance, not successful completion. AI Gateway sends the final outcome to your webhook when the run finishes. #### Webhook payload @@ -172,6 +172,8 @@ When the run completes, AI Gateway sends a single `POST` request to your `webhoo } ``` +Check `state` to determine the final outcome. A value of `Completed` indicates success. A value of `Failed` indicates failure, and `error` contains the error message. + Webhook delivery is best-effort and is not retried. The destination must be an HTTPS URL that does not resolve to a private network address. #### Webhook format