Error Codes

Understand common HTTP error codes in Yukkai — 402 (insufficient credit), 403 (access forbidden), 429 (rate limit), and 5xx (provider errors) — and how to resolve them.

When using Yukkai, you may encounter HTTP error codes related to billing, access, rate limits, or provider issues. This guide explains the most common errors and how to resolve them.

HTTP 402 — Payment Required

Symptoms

  • "Payment required"
  • "Insufficient credits"
  • "Wallet balance too low"
  • "OpenRouter balance exhausted"

Probable Causes

  1. Yukkai Wallet balance is insufficient — you don't have enough credits to complete the request.
  2. Your personal OpenRouter balance is insufficient — if using a personal sk-or-... key, your OpenRouter account is out of credit.
  3. A child key has reached its budget — the child key you're using has exhausted its allocated budget.
  4. The selected model costs more than your remaining balance — the model you're trying to use is too expensive for your current balance.

Resolution

  1. Identify which billing method is active:

  • If using Fusion, Frontier, or Yukkai-managed services → check the Yukkai Wallet.
  • If using a personal OpenRouter key → check your OpenRouter balance.
  • If using a child key → check its assigned and remaining budget.

  1. Recharge the relevant account:

  • Yukkai Wallet → Settings → Credits → Add Credits (Stripe checkout).
  • OpenRouter → go to openrouter.ai and top up there.
  • Child key → create a new child key with a fresh budget (you can't add budget to an existing key).

  1. Select a lower-cost model — if your balance is low, switch to a cheaper model or use Yukkai Free.
  2. Confirm that the payment completed successfully before retrying — check your Stripe receipt or OpenRouter transaction history.

Verification

A low-cost test request succeeds after recharging.

HTTP 403 — Access Forbidden

Symptoms

  • "Forbidden"
  • "Access denied"
  • "Model not permitted"
  • "Region or provider restriction"

Probable Causes

  1. The provider does not allow the request — the upstream provider (OpenAI, Anthropic, etc.) blocked the request.
  2. The model is restricted for your account or region — some models have geographic or account-level restrictions.
  3. The API key lacks required access — your key doesn't have permission to use the requested model.
  4. A safety or provider policy blocked the request — the content triggered a safety filter.
  5. The connected service authorization is insufficient — a YukkaiConnect integration (GitHub, Slack, etc.) has expired or lacks permissions.

Resolution

  1. Read the exact error text — it often indicates which restriction applies.
  2. Try another compatible model or provider — if one model is restricted, switch to a different one.
  3. Confirm account and regional eligibility — some models are only available in certain regions or to certain account types.
  4. Reconnect the relevant integration if authorization expired — go to Settings → YukkaiConnect and re-authorize the service.
  5. Do not attempt to bypass provider or legal restrictions — if a model is restricted in your region, using a VPN or other workaround violates the provider's terms of service.
  6. Reformulate only when the request itself was misunderstood, not to evade policy — if a safety filter blocked your request, rephrase it to be clearer, not to trick the filter.

HTTP 429 — Too Many Requests

Symptoms

  • "Too many requests"
  • "Rate limit exceeded"
  • Repeated temporary failures during a Swarm
  • Requests work individually but fail under parallel load

Probable Causes

  1. Too many simultaneous calls — you're sending requests faster than the provider allows.
  2. The selected provider or model is rate-limited — some models have strict rate limits.
  3. A Swarm launched more concurrent work than the provider accepts — parallel agents are hitting the rate limit.
  4. Your OpenRouter key has account-level limits — OpenRouter enforces rate limits per key.
  5. Temporary provider congestion — the provider is experiencing high load.

Resolution

  1. Reduce the number of parallel agents — if running a Swarm, use fewer concurrent agents.
  2. Pause and retry failed tasks rather than restarting the entire Swarm — use swarm(action:"retry_failed") instead of re-running everything.
  3. Switch to another compatible model — some models have higher rate limits than others.
  4. Check OpenRouter key usage and limits — use yukkai_cloud(action:"openrouter_key_usage") to see your current rate limit.
  5. Avoid repeatedly sending the same request — if a request fails, wait a moment before retrying.
  6. Let Yukkai's retry or failover behavior complete where supported — some models have automatic retry logic.
  7. For persistent problems, use a provider or model with higher available capacity — switch to a less congested provider.

Verification

A single test request succeeds, followed by a smaller parallel workload.

HTTP 5xx — Provider Error

Symptoms

  • 500, 502, 503, or 504 errors
  • "Provider unavailable"
  • "Gateway timeout"
  • "Model temporarily overloaded"

Probable Causes

  1. Temporary provider outage — the upstream provider (OpenAI, Anthropic, etc.) is down.
  2. OpenRouter routing failure — OpenRouter's proxy is experiencing issues.
  3. Upstream model overload — the specific model you're using is overloaded.
  4. Network interruption — your internet connection or the provider's network is unstable.

Resolution

  1. Retry once after confirming connectivity — check your internet connection, then try again.
  2. Switch models — if one model is overloaded, try a different one.
  3. Use Fusion where automatic routing or failover is available — Fusion can automatically route to a different model if one fails.
  4. Retry only failed Swarm tasks — use swarm(action:"retry_failed") instead of re-running the entire plan.
  5. Avoid destructive repetition if a tool action may already have completed — if a request failed after partially completing (e.g. a file was created but the response was lost), don't blindly retry — check the state first.
  6. Wait a few minutes — most provider outages are temporary and resolve within minutes.
  7. Check provider status pages — visit the provider's status page (e.g. status.openai.com, status.anthropic.com) to see if there's a known outage.

Other Common Errors

HTTP 401 — Unauthorized

Cause: Your API key is invalid, expired, or revoked.

Resolution:

  1. Check that your key is correct (no typos, no extra spaces).
  2. If using a Yukkai key, verify it hasn't been regenerated (old keys are invalidated).
  3. If using a child key, verify it hasn't been killed.
  4. If using a personal OpenRouter key, check that it's still valid on openrouter.ai.

HTTP 400 — Bad Request

Cause: The request is malformed (invalid parameters, unsupported model, etc.).

Resolution:

  1. Check the exact error message — it usually indicates which parameter is invalid.
  2. Verify the model id is correct (e.g. anthropic/claude-opus-4, not claude-opus-4).
  3. Verify required parameters are present (e.g. messages array for chat completions).
  4. Check that the model supports the features you're using (e.g. vision, tools).

Network Errors (No HTTP Code)

Cause: No internet connection, DNS failure, or firewall blocking the request.

Resolution:

  1. Check your internet connection.
  2. Verify you can reach openrouter.ai or yukkai-proxy.yukkai-api.workers.dev in a browser.
  3. Check your firewall or VPN settings.
  4. Try disabling VPN or proxy temporarily.

Troubleshooting Workflow

When you encounter an error:

  1. Read the exact error message — it often tells you what's wrong.
  2. Check for 401, 402, 403, 429, or 5xx — these are the most common billing/access/rate-limit errors.
  3. Identify which billing method is active:

  • Yukkai account key → check Wallet balance.
  • Personal OpenRouter key → check OpenRouter balance.
  • Child key → check child key budget.

  1. Check your internet connection — many "errors" are just network issues.
  2. Try a different model — if one model is failing, switch to another.
  3. Check provider status pages — see if there's a known outage.
  4. Reduce parallel load — if running a Swarm, use fewer agents.
  5. Wait and retry — many errors are temporary.
  6. Contact support — if none of the above resolves the issue.

Error Code Quick Reference

Code Meaning Common Cause Resolution
400 Bad Request Malformed request, invalid model id Check parameters, verify model id
401 Unauthorized Invalid or revoked API key Verify key, regenerate if needed
402 Payment Required Insufficient balance Recharge Wallet/OpenRouter/child key
403 Forbidden Model restricted, region blocked, safety filter Try different model, check eligibility
429 Too Many Requests Rate limit exceeded Reduce parallel load, switch model, wait
500 Internal Server Error Provider outage Retry, switch model, check status page
502 Bad Gateway OpenRouter routing failure Retry, switch model
503 Service Unavailable Provider overloaded Wait, retry, switch model
504 Gateway Timeout Provider timeout Retry, switch model

Examples

User gets HTTP 402

User: "I'm getting an error that says 'Payment required'. What does that mean?"

Yukkai: "HTTP 402 means your balance is insufficient. If you're using Yukkai Fusion or Frontier, check your Wallet balance in Settings → Credits and top up if needed. If you're using a personal OpenRouter key, check your OpenRouter balance on their website. If you're using a child key, it may have exhausted its budget — you'll need to create a new one."

User gets HTTP 429 during a Swarm

User: "My Swarm is failing with 'Too many requests' errors."

Yukkai: "You're hitting the provider's rate limit. Reduce the number of parallel agents in your Swarm, or switch to a model with higher rate limits. You can also use swarm(action:'retry_failed') to retry only the failed tasks instead of restarting the entire plan."

User gets HTTP 403

User: "I'm getting 'Access denied' when I try to use a specific model."

Yukkai: "HTTP 403 means the model is restricted — either by region, account type, or provider policy. Try a different model, or check if the model is available in your region. Don't attempt to bypass provider restrictions with a VPN, as that violates their terms of service."

User gets HTTP 503

User: "I'm getting 'Service unavailable' errors."

Yukkai: "HTTP 503 means the provider is temporarily overloaded or down. Wait a few minutes and retry, or switch to a different model. You can also check the provider's status page to see if there's a known outage."

Good to Know

  • Most errors are temporary — retry after a few seconds or minutes.
  • 402 errors mean you need to recharge — check Wallet, OpenRouter, or child key budget.
  • 429 errors mean you're going too fast — reduce parallel load or switch models.
  • 5xx errors mean the provider is down — wait or switch models.
  • Always read the exact error message — it usually tells you what's wrong.

Learn More

Last updated: July 19, 2026