Errors and debugging
Understand API errors and collect the details needed to troubleshoot a request.
Check the HTTP status and error body first. For a stream, also check for an error event or an incomplete response after streaming begins.
Common problems
| Problem | What to check |
|---|---|
| Cannot connect | API hostname, network and client timeout |
| Authentication rejected | Key header, expiry, disabled/revoked state and environment |
| Request forbidden | Inference key type and its organization binding |
| Credit or usage-limit refusal | Workspace credit and applicable usage limits |
| Model or parameter rejected | Exact model ID, selected endpoint and supported fields |
| Provider error | Returned error details; retry only when appropriate |
| Stream ends unexpectedly | Error events, cancellation and connection loss |
Find model IDs through Models. The chosen model must support the request format.
Capture response headers
This Bash example saves the headers from a model-list request:
curl -sS -D response-headers.txt \
https://api.tokamak.sh/v1/models \
-H "Authorization: Bearer $TOKAMAK_API_KEY"Add the same -D response-headers.txt option to an inference request when debugging it.
| Header | Use |
|---|---|
X-Request-Id | HTTP request correlation, when returned |
X-Tokamak-Execution-Id | Inference execution identifier for usage lookup, when returned |
A request rejected before inference admission may have no execution ID. Provider IDs inside the response are separate from Tokamak's execution ID.
Check a completed request
Save the execution ID as EXECUTION_ID, then query:
curl -sS --get https://api.tokamak.sh/v1/generation \
-H "Authorization: Bearer $TOKAMAK_API_KEY" \
--data-urlencode "id=$EXECUTION_ID"The response includes usage and billing status when available. Settlement can still be pending; see Usage.
Retry carefully
Use bounded retries with backoff for transient failures. Correct invalid credentials or request parameters before retrying.
A new inference POST can perform new work and create another charge. The optional X-Client-Request-Id header helps correlate requests; it does not prevent duplicate execution.
For streams, HTTP success means the stream started. Handle its terminal and error events as described in Streaming.
Ask for help
Share the API environment, UTC timestamp, model, endpoint, status/error code, and available request and execution IDs. Redact API keys, authorization headers, cookies and private prompt content.