references/ai-gateway/troubleshooting.md
AI Gateway Troubleshooting
Identify the request path and whether the failure comes from gateway access, upstream provider authentication, or request policy before changing credentials or retry behavior. A status code alone does not establish the failing layer.
| Symptom or task | Current documentation | |-----------------|-----------------------| | Authentication or provider errors, timeouts, DLP failures, or unexpected cache behavior | Troubleshooting | | Gateway authentication failure | Authenticated Gateway and REST API authentication | | Provider key or billing mismatch | BYOK, Unified Billing, and the provider guide | | Rate limits or repeated failures | Rate limiting and request handling | | Unexpected cache hit or miss, including streaming behavior | Caching | | Missing logs, collection overrides, or storage limits | Logging and limits | | Inspect headers, request metadata, usage, or export logs | Header glossary, custom metadata, analytics, and Logpush | | Dynamic route failure | Dynamic route usage |
Check the existing SDK and gateway retry settings together before adding another retry loop. Follow SDK integration when an endpoint or model format is suspect.