Troubleshooting

Common ACE gateway problems and their fixes: 401 and 402 errors, Bedrock and Azure credential pitfalls, overload and timeout errors, and testing without a provider bill.

• 401 invalid_developer_key with a valid provider keyThe gateway needs its own ACE developer key on every call; a provider key alone leaves the request with no ACE identity.
• Is this error from ACE or from the provider?Read the x-ace-error response header: present on every error ACE originated, absent on a vendor error relayed from upstream.
• 402 onboarding_incompleteThe key authenticated, but there is no provider key (stored or pass-through) or no model and no router to serve the request with.
• Bedrock 400 naming both credential headersSend a Bedrock API key or an access-key pair, never both; a key beside a pair, or half a pair, is a 400.
• Bedrock 400 with an API key and no regionA Bedrock API key needs x-ace-aws-region: a short-term key is bound to the region it was minted in, so ACE will not default one.
• Azure: x-ace-azure-deployment is ignored or returns 400x-ace-azure-deployment is deprecated. The deployment is the request's model (the path segment), or a per-model mapping in the stored Azure config.
• 503 overloaded with Retry-AfterACE shed the request on its own capacity, not the provider's. Back off for the Retry-After it sends, or send direct to the provider.
• Stream ends with a gateway_timeout error eventA stream silent past ACE_STREAM_IDLE_S (300 s) or open past ACE_STREAM_DEADLINE_S (3600 s) is closed with one terminal error event.
• Test an integration without a provider billEcho mode answers from the gateway's own echo terminal: no provider call, no provider key needed, nothing billed.