Troubleshooting
When a call doesn't behave the way you expect.
- Arabic text from the API looks garbled. How do I fix it?It's an encoding issue on your side: read and write UTF-8 everywhere, and use an RTL-aware display.Troubleshooting
- I get 404 errors on every request. Is my base URL wrong?Use https://api.gateway.clatterlabs.xyz/v1 as the base URL; the SDK adds /chat/completions.Troubleshooting
- I get connection or SSL errors when calling the Model API.Check your network, proxy and system certificates; the API is HTTPS only.Troubleshooting
- I get model_not_found but the model id is right. Why?Your SDK may be pointed at another provider's base URL, or a library is overriding the model name.Troubleshooting
- My calls work locally but fail with 401 in CI or production. Why?The key or Account ID isn't set in that environment, or a different key is being used there. Check the secrets.Troubleshooting
- My key worked yesterday and now I get 401. What changed?The key may have been revoked or expired, or the Account ID header changed. Check the exact 401 code.Troubleshooting
- My Model API bill is higher than I expected. Why?Long histories, reasoning tokens on Max/Heavy, prompts over 262K tokens and retries all add up. Check Logs.Troubleshooting
- My Model API call doesn't work. What should I check first?Check the base URL, both headers, the model id, credits, and the error code in the response body.Troubleshooting
- My request works in cURL but not in my SDK. Why?The SDK is probably missing the X-Clatter-Account default header, using another base URL, or calling a different endpoint.Troubleshooting
- My streaming code crashes with "choices[0] is undefined". Why?With include_usage, the final chunk has an empty choices array. Check choices before indexing.Troubleshooting
- SuperCosmos doesn't follow my system prompt. What can I do?Make instructions specific, put them in a system message, give an example, and try Max for complex rules.Troubleshooting
- SuperCosmos never calls my tool. Why?The description may not say when to use it, tool_choice may be none, or the request doesn't need it. Force it to test.Troubleshooting
- The Playground works but my API calls fail. Why?The Playground handles authentication for you. Check your own key, models:invoke permission and X-Clatter-Account header.Troubleshooting
- The reply's content is empty. Why?The model may have returned tool_calls instead of text, or used all max_tokens on reasoning. Check finish_reason.Troubleshooting
- Why are Model API responses slow?Max and Heavy think before answering; long prompts and outputs take longer. Stream, use Flash, or cap max_tokens.Troubleshooting
- Why do I get a different answer every time?Sampling is random by default. Lower the temperature and set a seed for steadier output.Troubleshooting
- Why is the answer cut off?finish_reason length means max_tokens or the model's output cap was reached. Raise max_tokens or ask for a shorter answer.Troubleshooting
Still need help?
Tried the steps above and still stuck? Email us. We usually reply within the first hour, and always within 24 hours. A full support team is with you.
Infrastructure questions, or permanent deletion of your data
infrastructure@clatterlabs.xyzFor deleting your whole account or the data of one service.