Troubleshooting
Resolve Maple Proxy connection, key, quota, model, browser and timeout problems using local checks, HTTP status codes and actionable error details.
Check the connection
Run curl http://127.0.0.1:8080/health. This only checks the local proxy; it does not contact Maple. If refused, start the proxy, check the host/port, publish Docker’s port, or keep the desktop app open. Use 127.0.0.1 for the default address.
If desktop key creation fails, create a key manually and set it in Local Proxy. The first inference request can take longer while the proxy verifies Maple’s enclave.
Read the error
Inspect the HTTP status and error.code or x-opensecret-error-code when present. Some HTTP rejections have no JSON body.
| Status / detail | What to do |
|---|---|
401 | Supply a real, unrevoked key. Remove placeholder keys. CORS mode requires a key with every request. |
400, unsupported_value | Check the exact model ID and supported thinking level. |
403, usage_limit_reached or free_tier_token_limit_exceeded | Review remaining credits and plan limits in API & credits. |
403, model_not_available_on_plan | Choose an included model or change your plan. |
Desktop 403, browser origin | Enable CORS and send a real key; see browser access. |
404 | Check the base URL and supported API routes. Responses API requests are unsupported. |
413 | Reduce context for message_exceeds_context_limit; otherwise check the 50 MiB request-body limit. |
429 / 503 | Check status, reduce concurrency and respect Retry-After when present. |
502 | Check network access and automatic date/time settings; update an old proxy. |
504 or a stopped stream | Reduce the prompt or increase request/idle timeouts. |
Retries do not guarantee a request runs only once. For persistent failures, record the proxy version and error details. Enable MAPLE_DEBUG=true for standalone logs if needed; remove secrets before sharing them in a support issue.
Last updated