AI Gateway Standardizes Provider Credential Errors on HTTP 401

Hi everyone, it's Shii-chan! Today there's a change that AI Gateway users should check their error handling for!

Cloudflare Changelog developers.cloudflare.com

What was announced?

The Cloudflare Changelog announced that AI Gateway's REST API now returns consistent responses when an AI provider rejects credentials. The change applies to POST /ai/run.

The story so far

The same "credentials rejected" situation produced different responses depending on the provider:

• ElevenLabs: a provider-specific UserCredentialsError with HTTP 403
• Google Vertex: HTTP 500, with upstream retries
• All other providers: HTTP 402 or another provider-specific status

What changes

Rejected credentials now come back as HTTP 401 with error code 2009 for every provider. For Google Vertex, the request now fails without retrying the provider.

Dive Deep

The new responses at a glance:

• ElevenLabs: HTTP 401 with error code 2009
• Google Vertex: HTTP 401 with error code 2009 (no retries)
• All other providers: HTTP 401 with error code 2009
• When using Unified Billing and the provider rejects the credentials: HTTP 503 (previously a provider-specific authentication error)

If your application handles AI Gateway REST API errors, update it to treat HTTP 401 as an invalid or rejected provider credential. For how to provide credentials, see "Bring your own provider keys".

Wrap-up

• Credential rejections on POST /ai/run are unified as HTTP 401 with error code 2009
• Google Vertex no longer returns 500 or retries, and fails right away
• Unified Billing returns HTTP 503
• Update your app to treat 401 as an invalid provider credential

A must-check for developers calling multiple providers through AI Gateway!