Errors
An error answer has this JSON body:
Every answer has an x-request-id header, also an error answer.
A job can fail after the API accepted it. That is not an error answer: the answer is 200 with a job in the failed status. Read the job error codes.
400
invalid_request
The body, the query or a header is not valid. details lists the issues. An unknown notify.endpoint also gives this code. The API creates no job.
A size limit of Machines also gives this code, with details.limit: the name of the limit, and details.max. A tool output or an answer that does not match its schema gives this code too, and the run continues to wait for it.
wait_out_of_range
Prefer: wait or ?wait is outside 1 to 90, or is not a whole number. Use a value from 1 to 90.
deadline_not_supported
The deadline field has a value other than asap. Send "asap" or leave out the field.
procedure_invalid
The procedure of a Machine does not compile. details.diagnostics lists each problem as {level, code, path, message}. The API saves nothing and creates no job. Fix the procedure, then send it again. Read the lint codes. POST /v2/machines/lint gives the same diagnostics, with no error.
401
missing_credential
The request has no Authorization header. Send Authorization: Bearer <credential>.
invalid_api_key
The crk_ key has a bad format or tag, is for another host, or is unknown, revoked or expired. Check the key and the host.
invalid_token
A crt_ token or a JWT fails a check. Read the token checks. A crt_ token also fails when its trust changes. Exchange the JWT again.
402
credits_exhausted
The organization has no paperwork credits. Add credits in Dash. Test keys and live keys share the balance. Reads, for example GET /v2/me, still work.
403
insufficient_scope
The credential does not have the scope of the route, or the agent is not on the allowlist of the key.
production_access_disabled
The organization cannot use live credentials. Use a test key, or contact CloudRaker.
test_key_not_allowed
A test key called a Run path or /v2/agents. Run has no test mode. Use a live key.
404
not_found
The host is not a tenant host, or the route does not exist. On the Machines routes, no Machine or version has this name. The API creates no job.
tenant_not_found
The slug of the host has no API keys yet. An admin creates the first key in Dash.
job_not_found
No job with this id exists, or the credential cannot read it. Read Access to a job.
409
idempotency_key_reused
The same credential sent this Idempotency-Key with another body. Use a new key for a new request. Read Idempotency.
job_not_cancellable
The job already ended.
version_conflict
The base_version of a Machine save is not the latest version. Another writer saved a version after your read. details.latest_version is the latest version. Read that version, merge your change, then save again with the new base_version.
not_waiting
A Machine run does not wait for this tool output, answer or input. details.reason says why:
details.required_action is what the run waits for now, or null. A second send of an output that the run already took is not an error: the answer is the run. Read The run loop.
429
rate_limit_exceeded
The requests bucket or the units bucket is empty. Wait for the time in the retry-after header. Read Rate limits.
concurrency_limited
Too many jobs of this class run at the same time, or too many streams are open. Wait for the time in retry-after, then try again.
A Machine run start also gives this code when the organization has too many active runs: 20 with test keys, 500 with live keys. The API creates no job.
500
internal_error
An unexpected error occurred. Try again. If it continues, send the requestId to support.
503
capability_unavailable
The capability did not answer, or the API cannot check credentials now. Try again later. The API deletes the Idempotency-Key claim of a job that fails this way, so a retry with the same key creates a new job.
OAuth errors
POST /v2/oauth/token uses the RFC 6749 error shape, and the x-request-id header:
Test a token on the Trusted issuers page of Dash shows why a token fails.
OpenAI route errors
The OpenAI compatible routes (/v2/models and /v2/chat/completions) use the OpenAI error shape, and the x-request-id header:
code is a code of this page, or one of the codes below. type comes from the status. Read Errors of the OpenAI compatible API.
model_not_found
404. No Machine or version has this model id, or the id is not machine/<name> or machine/<name>@<version>.
unsupported_parameter
400. The request has a field that the API refuses, for example stream: true. param names the field.
invalid_tool_call_id
400. The tool call ids of one assistant message name more than one run, or a tool message answers no tool call of the run.
tools_mismatch
400. The tools of the request do not name each caller tool of the Machine version.
inputs_required
400. A new run has no value for a required input. Send the inputs in machine_inputs.
tool_output_required
400. A user message came when the run waits for a tool output or for a person. Send a tool message for the pending tool call.