api_base Troubleshooting

Every provider key that uses the openai adapter resolves its upstream URL from one field: api_base. Almost every provider-specific setup guide in this section has its own "Upstream 404" or "Upstream configuration error" troubleshooting row, and most of them trace back to one of the same handful of api_base mistakes. This page collects those patterns in one place so you can check them before opening a provider's individual guide.

For what api_base is and how AISIX builds the outbound request from it, start with Adapter Protocol Families. This page is about diagnosing a value that is already wrong, not about adapter selection.

The Four Recurring Mistakes

1. The Root Stops at the Wrong Path Segment

AISIX appends the endpoint path, such as /chat/completions or /embeddings, directly to whatever you set as api_base. Two mistakes come from getting that split wrong:

• Too shallow. Setting api_base to a bare host such as https://api.deepinfra.com produces https://api.deepinfra.com/chat/completions, which most vendors do not serve — the vendor's documented root almost always includes a version segment such as /v1. AISIX does not synthesize a missing path segment for a non-OpenAI vendor, and it does not fall back to another vendor's host to compensate. See Why the Base URL Stops at /v1 on the DeepInfra page for a worked example of this exact failure.
• Too deep, with a doubled version segment. Setting api_base to a value that already ends in a version segment your target route adds itself produces a doubled path. Add a Rerank Model on the Cohere page documents this precisely: its rerank route inserts /v1 whenever the base does not already end in /v1, so setting api_base to https://api.cohere.com/v2 builds https://api.cohere.com/v2/v1/rerank and fails upstream.

Check the provider's own guide for the exact root it expects — the depth is vendor-specific and is not something AISIX can validate for you at write time.

2. A Full Endpoint URL Was Pasted Instead of the Root

It is common to copy a complete example URL, such as one ending in /v1/chat/completions, directly out of a vendor's own API reference and paste it into api_base. AISIX strips a small set of known endpoint suffixes and a trailing slash when it recognizes them, so this sometimes still works — the DeepInfra and Cloudflare Workers AI pages both document that stripping behavior. Do not rely on it: the recognized suffix list is not exhaustive across every provider and route, and the shorter root form is what stays readable when you or a teammate reads the configuration back later. Store the root the provider's guide documents, not the full endpoint you copied.

3. api_base Was Left Empty for a Provider That Requires It

For direct providers such as OpenAI, Anthropic, and Azure OpenAI, AISIX has a curated default and api_base is optional. For most community catalog providers, it is not: the DeepInfra page explains that models.dev publishes no default api field for that provider, so create fails with a 400 error naming the missing default rather than silently falling back to another host. AISIX never substitutes the OpenAI host as a fallback for a non-OpenAI provider — that would risk sending a provider-specific credential to the wrong vendor. If create succeeds with api_base unset, check whether the provider guide describes an admin-API-filled default (see the next section) before assuming the field is truly optional.

4. An Account-Scoped Template Was Stored Literally

A handful of community catalog providers publish an api_base template that includes a placeholder for your account ID rather than a single fixed root. Supply What the Community Catalog Does Not on the Cloudflare Workers AI page is the clearest example: the published default is https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1, a template rather than a resolved URL. AISIX performs no placeholder substitution. If you omit api_base expecting AISIX to fill in your account, the create request still succeeds, the literal ${CLOUDFLARE_ACCOUNT_ID} text is stored as written, and the first request fails at the upstream with no earlier warning. Always set the fully resolved, account-specific value yourself for providers shaped this way.

When the AISIX Enterprise Admin API Fills in a Default

Some catalog providers — Baseten and Cohere among them — let the AISIX Enterprise Admin API fill in a shared default root when you omit api_base on create. This is convenient, but it has two consequences worth knowing before you rely on it:

• The filled-in value is the provider's shared root (for example, the common Model APIs root for Baseten). It is not usable to distinguish one dedicated deployment from another on the same provider, so a setup that targets a specific deployment URL should still set api_base explicitly.
• Reading the resource back later does not tell you whether the value was admin-API-filled or explicitly set — set it explicitly in your own configuration so the intended target stays visible without cross-referencing the provider's own catalog defaults.

A Quick Diagnostic Order

When a provider key returns an upstream 404, connection failure, or "upstream configuration error" before any request reaches the provider:

1. Confirm api_base is set at all — an empty value on a provider that has no default fails immediately, per mistake 3 above.
2. Compare the stored value against the exact root the provider's own AISIX guide documents, not a value copied from the vendor's general API reference — check for depth mismatches and pasted full endpoints.
3. For a community catalog provider, check whether its root is account-scoped and confirm the placeholder was actually substituted.
4. If the request reaches the provider but fails authentication rather than routing, the problem is the credential, not api_base — see Provider Keys and the specific provider's guide.

Next Steps

• Adapter Protocol Families — how AISIX builds the outbound request from api_base and the adapter's protocol.
• Provider Compatibility — which routes each provider supports once requests reach it correctly.
• Your provider's own setup guide, linked from Choose a Provider Upstream — for the exact root and credential shape it expects.