Troubleshooting

    Authentication Errors

    Error messageHTTP statusCauseSolution
    invalid api key401The API Key is invalid, expired, revoked, or disabledGo to Console → API Keys and confirm the key status is "active". If it has expired, generate a new one

    Routing and Model Errors

    Error messageHTTP statusCauseSolution
    no model config found for: {model}404The requested model ID does not existOpen the model list and confirm the model ID is spelled correctly
    model field is required400The request body is missing the model fieldAdd "model": "model name" to the request JSON
    invalid or empty requested model400The requested model name is empty or invalidOpen the model list and confirm you are using the correct model ID format
    unknown api path404The API path is incorrectConfirm the Base URL is https://api.gate.ai/openai/v1 or https://api.gate.ai/anthropic

    Request Parameter Errors

    Error messageHTTP statusCauseSolution
    invalid JSON body400The request body is not valid JSONCheck that the request body is valid JSON
    failed to read request body400The request body could not be readConfirm the body is not corrupted and Content-Type is set to application/json
    failed to rewrite request body500Failed to rewrite the request body inside the gatewayRetry. If it keeps happening, contact technical support
    images are not supported by this model400The target model does not support image inputSwitch to a multimodal model that supports images, such as gpt-4o
    audio is not supported by this model400The target model does not support audio inputSwitch to a model that supports audio input
    unsupported parameter: max_tokens400Some models do not support the max_tokens parameterUse max_completion_tokens instead

    Quota and Rate Limit Errors

    Error messageHTTP statusCauseSolution
    api key budget quota exceeded429The API Key budget has been exhaustedGo to Console → API Keys → Budget settings, increase the budget, or wait for the quota to reset
    guardrail budget limit exceeded429The guardrail budget limit has been exceededCheck the budget limit in guardrail settings, then increase the limit or reduce usage frequency
    organization guardrail budget limit exceeded429The organization-level guardrail budget has been exceededContact an organization admin to adjust the organization-level budget limit
    model not allowed by guardrail policy403The model is not allowed by the guardrail policyGo to Console → Guardrails and add the target model to the allowlist
    The free model usage has reached its daily global limit today.429The global daily limit for the free model has been reachedWait for the next daily reset, or upgrade to a paid plan for unrestricted models
    The free model usage has reached its daily limit today.429Your personal daily limit for the free model has been reachedWait for the next daily reset, or upgrade to a paid plan
    Guest daily spending limit exceeded. Please try again tomorrow or upgrade to a paid plan.429The guest daily spending limit has been exceededRegister an account and upgrade to a paid plan, or wait for the next daily reset

    Billing and Balance Errors

    Error messageHTTP statusCauseSolution
    Pending payment {amount} USD — Please top up...402The account balance is insufficient and has an outstanding paymentTop up with Gate Pay
    Insufficient balance and account in debt402The balance is insufficient and the account is in debtTop up with Gate Pay
    billing model info not found for model "{model}"400Billing information for the model does not existConfirm the model ID is correct. If it is a new model, contact technical support to configure billing rules
    billing model info is ambiguous for model "{model}"400Billing information is ambiguous because multiple records matchContact technical support to check the model billing configuration
    billing configuration error500Billing rules are misconfigured on the serverContact technical support to fix the billing configuration

    Upstream Service Errors

    Error messageHTTP statusCauseSolution
    bad gateway502The gateway failed to communicate with the upstream serviceRetry. If it keeps happening, check the service status page or contact technical support
    upstream service unavailable502The upstream AI Provider is unavailableRetry later, or switch to another available model
    upstream service error502The upstream AI Provider returned an errorCheck whether the request parameters match the target model requirements. If it keeps happening, contact technical support
    request timeout504The upstream request timed outReduce the input length or increase the timeout, then retry
    no provider handler configured for protocol502No protocol handler is configured in the gatewayContact technical support to check the gateway configuration

    Server Internal Errors

    Error messageHTTP statusCauseSolution
    internal server error500Internal gateway errorRetry. If it keeps happening, contact technical support with the Request ID
    failed to record request log500Failed to record the request logThis does not affect the request result and can be ignored. Contact technical support if it happens frequently
    failed to list models500Failed to query the model listRetry. If it keeps happening, contact technical support

    Common Quick Checks

    Incorrect Base URL

    bash
    1# ❌ Incorrect2https://api.gate.ai/v1/chat/completions34# ✅ Correct5https://api.gate.ai/openai/v1/chat/completions  # OpenAI protocol6https://api.gate.ai/anthropic/v1/messages  # Anthropic protocol

    Incompatible max_tokens Parameter

    javascript
    1// ❌ Some models do not support this2{ "model": "gpt-4o", "max_tokens": 100 }34// ✅ Use max_completion_tokens5{ "model": "openai/gpt-5.5", "max_completion_tokens": 100 }

    API Key Format

    bash
    1# ✅ Correct request headers2Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx # OpenAI protocol3X-api-key: sk-xxxxxxxxxxxxxxxxxxxx # Anthropic protocol