SimpleTroubleshooting
Diagnose authentication, model, streaming, and upstream failures.
Check the HTTP status and content type before decoding the body. Chat errors generally have an error object, while media endpoints can also forward upstream error formats.
Error response shape
This is an illustrative error, not a promise of identical wording for every endpoint:
{
"error": {
"message": "Invalid API key provided.",
"type": "authentication_error",
"code": "invalid_api_key"
}
}Treat message, type, and code as optional when parsing error bodies. Some capacity errors contain only a message and type; an intermediary can also return a non-JSON response.
Status code guide
| Status | Meaning | First check |
|---|---|---|
| 400 | Invalid input or rejected request | JSON, parameters, context, content-policy message |
| 401 | Missing or invalid credentials | Bearer header and key validity |
| 402 | Insufficient credits | Account and key balances |
| 403 | Access denied | Account/model permissions |
| 404 | Unknown path, model or resource | Base URL, route, exact model ID |
| 429 | Rate, concurrency or capacity limit | Retry-After and active request count |
| 499 in logs | Client-side cancellation | Client deadline, disconnect, Stop action |
| 500 | Internal service failure | Capture safe diagnostics; bounded retry if appropriate |
| 501 | Endpoint not implemented | Use chat completions instead of legacy completions |
| 502 | Routing or upstream failure | Service availability and error timing |
| 503 | Temporarily unavailable | Capacity and bounded backoff |
| 504 | Timeout | Application deadlines and service availability |
A 404 with an otherwise valid key
Use https://api.simplellm.eu/v1 as the OpenAI-compatible SDK base URL. Do not append another /v1 or point inference requests to the dashboard host.
Use chat.completions.create, not a client's Responses API or legacy text-completion method. Check the compatibility page before assuming another OpenAI endpoint exists.
Empty answer or no visible output
Inspect choices, the finish reason, optional reasoning fields, and token usage. A small output budget can be consumed by reasoning. A tool call may intentionally have no ordinary text answer until your application returns a tool result.
For streaming, keep reading through role-only and usage-only events. Do not fail merely because one chunk has no text or no choices.
Invalid JSON while reading audio
Speech returns audio bytes on success. Transcription can return text formats depending on the requested output. Check Content-Type before calling a JSON parser, and use multipart form data for file uploads.
A stream fails after HTTP 200
The status was sent before generation finished. Catch read errors, inspect any stream error events, and mark the response incomplete if it ends without a valid completion.
Do not discard delivered output automatically or charge a new request to the user through an invisible retry. See stream handling.
Safe diagnostics for support
Record the timestamp with timezone, endpoint, model ID, HTTP status, time to first output, total elapsed time, and whether any output arrived. Include a request identifier if the response supplies one.
Remove Authorization headers, API keys, personal data, and sensitive prompts or images before sharing diagnostics. Reproduce with a minimal non-sensitive request where possible.
Security findings belong at security@stageone.solutions, following the reporting policy; do not submit automated bulk reports.