> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Errors

An error answer has this JSON body:

```json
{
  "code": "invalid_request",
  "message": "file is required.",
  "retryable": false,
  "requestId": "req_01JC9M…",
  "docUrl": "https://docs.cloudraker.com/paperwork/v2/errors#invalid_request"
}
```

| Field       | Meaning                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `code`      | A stable code. Switch on this value.                                                                  |
| `message`   | A text for a person. The text can change.                                                             |
| `retryable` | True when the same request can succeed later.                                                         |
| `requestId` | The value of the `x-request-id` header. Send it to support.                                           |
| `docUrl`    | The section of this page for the code.                                                                |
| `details`   | More 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](/paperwork/v2/jobs#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](/paperwork/v2/machines#limits) 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](/paperwork/v2/machines) 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](/paperwork/v2/machines-language#lints). `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](/paperwork/v2/oidc-trusts#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](/paperwork/v2/jobs#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](/paperwork/v2/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.reason`    | Cause                                                       |
| ------------------- | ----------------------------------------------------------- |
| `call_not_pending`  | No pending tool call has this id, or its deadline passed.   |
| `hold_not_open`     | No hold of the run waits for an answer with this `seq`.     |
| `input_not_awaited` | The run does not wait for an input with this name.          |
| `run_ended`         | The 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](/paperwork/v2/machines#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](/paperwork/v2/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:

```json
{
  "error": "invalid_grant",
  "error_description": "The token is not valid for this tenant, or no trust matches it."
}
```

| Status | `error`                  | Cause                                                                            |
| ------ | ------------------------ | -------------------------------------------------------------------------------- |
| 400    | `invalid_request`        | A required parameter is missing, or the body is not valid.                       |
| 400    | `invalid_grant`          | The JWT fails a check, or no trust matches it. The description does not say why. |
| 400    | `unsupported_grant_type` | The `grant_type` is not supported.                                               |
| 400    | `invalid_target`         | The `audience` or `resource` is not the tenant host.                             |
| 429    | `invalid_request`        | Too many token requests. Wait for the time in `retry-after`.                     |
| 503    | `invalid_request`        | The issuer did not answer. The same request can pass later.                      |
| 500    | `invalid_request`        | An unexpected error occurred.                                                    |

**Test a token** on the [Trusted issuers](https://dash.cloudraker.com/trusted-issuers) page of Dash shows why a token fails.

## OpenAI route errors

The [OpenAI compatible routes](/paperwork/v2/machines-openai) (`/v2/models` and `/v2/chat/completions`) use the OpenAI error shape, and the `x-request-id` header:

```json
{
  "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](/paperwork/v2/machines-openai#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.