Skip to content
Developer docs

Errors and request references

The error body every REST endpoint returns, what the status codes mean, and how to trace a failed call with its request reference.

Every REST error answers with the same JSON body:

{
  "detail": "Unauthorized",
  "hint": "Sign in again to continue.",
  "retryable": false,
  "request_id": "64b9802f04d348ae88b698192076f425"
}

Field

Meaning

detail

What went wrong, in plain words, safe to show to a person

code

A stable code you can branch on (for example plan_limit_reached or connection_not_set_up); present on refusals from the error map

hint

What to do about it

retryable

true when the same call may succeed later unchanged

request_id

The reference of this request

feature, policy

Present when a plan feature or a policy refused the call

A 422 (validation) answers {"detail": [...]} with one entry per field, naming the field and the problem.

Status codes

Status

Meaning

400

The request cannot be done as asked (for example a job that is already running)

401

No token, or an unknown, expired or revoked one

403

Allowed for nobody in your position: your role, the token's binding, your plan, or a policy

404

Does not exist, or you may not know it exists

409

Conflicts with the current state (for example held by a release rule)

422

The body does not match the schema

429

Too many attempts; wait and try again

5xx

Our fault; retryable says whether to try again

Tracing a failed call

Every answer carries its reference. In the console, Activity > Requests, search the request_id: you see its audit entries in order and the work it started. Support can find the same request from the reference alone; quote it when you write to support@remplatforms.com. Over MCP, the tool error_find_reference does the same, and error_explain explains any code.

Download: PDF · Word · Markdown