FAQ
This page collects common troubleshooting steps for Potato API. When a request fails, first check your API key, quota, model name, token group permissions, and endpoint URL.
Quick Diagnosis
4xx errors usually point to client-side configuration or request issues. 5xx errors usually point to gateway or upstream service issues; retry later and keep the request-id for support.
Basic Checklist
| Item | What to Check |
|---|---|
| API key | Make sure the key is copied completely, has no extra spaces, and is not disabled. |
| Account quota | Confirm that your balance or token quota is still available in the console. |
| Model name | Copy the full model ID from Model Square or the console. Do not edit it manually. |
| Token group | Confirm that the API key's group has permission to call the model. |
| Base URL | Confirm it is https://www.potatoai.cc/v1 and does not miss /v1. |
Error Code Reference
HTTP status codes help identify whether the problem belongs to the client, gateway, or upstream service.
| Status | Meaning | Common Cause | Recommended Action |
|---|---|---|---|
| 200 | Success | Normal response; if the body is empty, the endpoint may be wrong. | Check whether the endpoint matches the model or API type. |
| 400 | Bad request | Invalid JSON, missing fields, invalid parameters, or misspelled model name. | Recheck the request body and model name. |
| 401 | Unauthorized | API key is missing, incorrect, or disabled. | Check the Authorization: Bearer sk-xxx format. |
| 403 | Forbidden | The key has no access to the model or current token group. | Check token group permissions in the console. |
| 404 | Not found | URL typo, such as /v1/message instead of /v1/messages. | Call /v1/models to verify; check URL spelling. |
| 413 | Request too large | Prompt or input exceeds the model context window. | Shorten the input, or switch to a larger-context model. |
| 429 | Rate limited | QPS limit reached, or account quota is exhausted. | Reduce concurrency and check quota in the console. |
| 500 | Upstream error | Upstream model service error. | Wait 30 seconds and retry; if it persists, submit a ticket with the request-id. |
| 502 | Gateway error | Connection issue between the gateway and upstream service. | Wait 1 minute and retry. |
| 503 | Service unavailable | Upstream overload or maintenance. | Wait 1-5 minutes and retry. |
| 504 | Gateway timeout | Upstream response is slow, or the prompt is too long. | Shorten the input, or enable streaming output. |
| No response / stuck | No response or request stuck | Local network, DNS, TLS issue, or inaccurate system time. | Check the network, switch DNS, and correct the system time. |
Additional Notes
4xx Errors
4xx errors are usually client-side issues, such as incorrect keys, model names, URLs, request bodies, or permissions. In most cases, you can fix them by checking your local configuration.
5xx Errors
5xx errors are usually gateway or upstream model service issues. Retry after a short wait; if the issue continues, submit a ticket with the request-id, time, model name, and brief request scenario.
Pricing or Quota Looks Different
If model pricing, available models, or quota usage differs from expectations, refer to the console and final billing records.