When an AI API integration fails, the HTTP status and provider error code usually narrow the problem faster than a generic reinstall or network reset. Capture one failing request from the same environment where the app runs, remove secrets from the log, and follow the branch below. A successful local test does not prove production is configured the same way.
Scope: This is a diagnostic workflow for hosted AI APIs, with OpenAI and Google Vertex AI documentation as concrete examples. Exact endpoints, model names, authentication methods, quotas, and SDK behavior depend on the provider and version. Check the provider’s current reference for your integration.
1. Record the failure without exposing credentials
Write down the request time, environment, endpoint path, SDK version, HTTP status, provider error code or message, and any request ID. Log the request shape and model name, but redact API keys, authorization headers, user data, and private prompt content. Reproduce with one minimal request that uses the same credentials and deployment environment. This separates a general provider problem from one application’s configuration.
2. For 401 or 403, check identity and permissions
A 401 usually calls for checking which key or token the running process actually loaded, whether it is still active, and whether it belongs to the intended project or organization. A 403 can mean permission, policy, region, or resource-access restrictions depending on the provider. Do not assume that generating a new key fixes every 403. OpenAI’s error-code guide distinguishes several authentication and access failures. For Vertex AI, check the service account, enabled APIs, model access, and permissions on referenced data using Google’s inference error guide. Google Cloud’s Application Default Credentials guide explains why local and deployed workloads may select different credentials.
3. For 400 or 404, compare the request with the current API reference
Check the base URL, API version, path, model identifier, required fields, content type, and input size. A 400 often means the provider rejected the request parameters; a 404 may mean the requested model or resource is unavailable to that project, or the URL is wrong. Read the provider’s error body rather than treating all 4xx responses as network failures. If the application uses a third-party SDK or plugin, confirm that it supports the provider’s current request format and that its configured model is still available.
4. For 429, separate rate limiting from exhausted quota
Inspect the provider-specific error code, usage dashboard, and response headers. OpenAI documents distinct 429 causes, including temporary request rate limits and credit, spend, or usage limits. Retrying a billing or quota error will not restore access. For a temporary rate limit, honor a valid Retry-After header, slow the request rate, and use bounded exponential backoff with jitter. Account for retries already performed by your SDK so nested retry loops do not multiply traffic. See OpenAI’s rate-limit guidance.
5. For timeouts and connection failures, test the deployment path
Check DNS resolution, TLS certificate validation, outbound HTTPS access, proxy configuration, and the application’s request deadline from the server or container that actually fails. A timeout can occur before a provider returns any HTTP status, so it should not be labeled “401” or “rate limit” without evidence. Compare a small request from development and production using the same endpoint and record the difference. Do not disable a firewall or certificate checks as a general fix.
6. For 5xx or overload, retry carefully and verify recovery
Provider-side failures may be temporary. Check the provider’s status page and the error code; retry only when the operation is safe to repeat, use a bounded delay, and follow Retry-After if supplied. If an operation may have succeeded before a timeout, check its result or use the provider’s idempotency or job-status mechanism before resending it. Once a minimal request works, restore normal traffic gradually and monitor errors and latency.
When to escalate
Give the provider or integration maintainer the redacted status, error code, request ID, timestamp with time zone, endpoint, SDK version, and steps to reproduce. Keep keys and private input out of the ticket. If only one third-party app fails while a documented direct request succeeds, start with that app’s maintainer.
Sources and limits
The linked OpenAI API error and rate-limit guides and Google Vertex AI/Cloud authentication guides support the provider-specific examples. They do not imply every AI API uses the same codes or retry policy. This guide does not claim to have tested the reader’s account, application, or network.
