Skip to navigation

Errors

One error body. Each code has its own section on this page.
View as Markdown

An error answer has this JSON body:

{
"code": "invalid_request",
"message": "file is required.",
"retryable": false,
"requestId": "req_01JC9M…",
"docUrl": "https://docs.cloudraker.com/paperwork/v2/errors#invalid_request"
}
FieldMeaning
codeA stable code. Switch on this value.
messageA text for a person. The text can change.
retryableTrue when the same request can succeed later.
requestIdThe value of the x-request-id header. Send it to support.
docUrlThe section of this page for the code.
detailsMore data on some codes: the issues of invalid_request, and the fields of the Machines codes below.

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.reasonCause
call_not_pendingNo pending tool call has this id, or its deadline passed.
hold_not_openNo hold of the run waits for an answer with this seq.
input_not_awaitedThe run does not wait for an input with this name.
run_endedThe run ended. It takes no more outputs, answers or inputs.

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:

{
"error": "invalid_grant",
"error_description": "The token is not valid for this tenant, or no trust matches it."
}
StatuserrorCause
400invalid_requestA required parameter is missing, or the body is not valid.
400invalid_grantThe JWT fails a check, or no trust matches it. The description does not say why.
400unsupported_grant_typeThe grant_type is not supported.
400invalid_targetThe audience or resource is not the tenant host.
429invalid_requestToo many token requests. Wait for the time in retry-after.
503invalid_requestThe issuer did not answer. The same request can pass later.
500invalid_requestAn unexpected error occurred.

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:

{
"error": {
"message": "The model \"machine/unknown\" does not exist.",
"type": "not_found_error",
"param": "model",
"code": "model_not_found"
}
}

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.