Troubleshooting
Troubleshooting
Practical guidance for using NeonAPI.
Start with the response
Keep the HTTP status, redacted response body, model ID and request identifier. An upstream may use a protocol-specific error format, so the actual response is more useful than the status alone.
| Status | First checks |
|---|---|
| 400 | JSON structure, required fields, supported parameters and context limits |
| 401 | Correct key, Bearer prefix, whitespace and expiry |
| 402 / insufficient quota | Account balance, plan and key quota |
| 403 | Key restrictions, model access and account state |
| 404 | Base URL, endpoint path and exact model ID |
| 429 | Concurrency, rate limits, quota and provider capacity |
| 5xx | Service status and upstream response; retry with backoff when appropriate |
Narrow down the cause
- Test one short request using cURL.
- Compare the model ID, key and URL with the client settings.
- Remove optional parameters and attachments, then reintroduce them one at a time.
- Check usage logs before repeating a task that may already have started.
Share a useful report
Include a timestamp with time zone, endpoint, model ID and redacted error. Never share Authorization headers or full sensitive request bodies.