Errors and reason codes

A robot hears "no" in two ways. An HTTP error means the request couldn't be answered as sent: a signing problem, a bad body, too many requests. A refusal is a normal answer, HTTP 200, that says the building won't let your robot through now, and why. Handle them separately: fix an HTTP error in your software, and act on a refusal's code.

The error body

Every HTTP error has a JSON body:

{"code": "signature_mismatch", "error": "signature mismatch", "time": 1792562594.0, "request_id": "ece7c2db7072b481"}

• code: a stable code for your software. Where nothing more particular applies, it's the status's own code, from the table below.
• error: plain words, for people and logs. The words may change, so act on code.
• request_id: this request's ID. Every answer, error or not, also carries it in the X-Request-Id header. Quote it when you write to Plynth about a call.
• time: on a 401 only, the gateway's clock in unix seconds, to check yours against.

New codes may be added. Handle one you don't know by its status.

Status codes

Asking for a door or elevator that doesn't exist isn't a 404: it's a refusal, unknown_resource.

When you get 401

In the raw answer, the ± arrives escaped, as \u00b1: compare code, or compare error after parsing the JSON. After Rotate on your company's page, the old secret works for 24 hours more; after Revoke Old, or when the building replaces a secret, it gets signature_mismatch at once. The gateway logs every refused call, so fix the cause before you send again.

429 and Retry-After

Requests are limited per robot and per caller address. The sandbox's limits are on the sandbox page; a building may set its own. A 429 carries Retry-After, in whole seconds, at least 1, and the same number as retry_after in its body: wait that long, then send again (the kit's client gives it as GatewayError.retry_after). Handle 429 by its status, and back off further if they keep coming.

Sending again safely

• No answer is a timeout, a dropped connection, or a 502, 503 or 504 that isn't the gateway's own JSON. Treat it as no, and use your own fallback; the kit's client raises it as URLError, an OSError, never GatewayError. Then send the same passage request again, unchanged, with the same passage_id: you get its current status, and no second command is sent. Reconnect a dropped stream with Last-Event-ID.
• After a 503 from the gateway itself, do the same.
• The reports passed, boarded and exited, a cancel, and a check-in are each safe to repeat.
• A call that got 400, 401, 403, 404 or 409 gets the same answer if you send it again unchanged.

Methods

The API takes GET and POST. HEAD answers the public pages (/v1/health, /v1/openapi.yaml, /docs and its pages, /status) with their headers and no body; anywhere else, it's 405. OPTIONS answers 204 with Allow: GET, POST, OPTIONS, and HEAD too on the public pages. PUT, PATCH and DELETE answer 405, with the same Allow.

GET /v1/health needs no signature and answers {"ok": true}, with the gateway's release in the X-Gateway-Release header and the API's version in X-Api-Version. Watch it from your own monitoring.

Refusals

A refusal is a normal answer, HTTP 200, with state DENIED, or FAILED if something stops the passage later:

{"passage_id": "3f2b9c1e-6a4d-4e8b-9f1a-2c7d5e0b8a14", "resource_id": "lift", "state": "DENIED",
 "reason": "closed: Car being serviced", "reason_code": "closed", "retry": true, "retry_after": 1200,
 "car": null, "done": false, "approval_code": null, "line": null, "alone": false, "arrived": null}

• Act on reason_code, never on the words in reason.
• retry is true if waiting can help, and false if it needs the owner or your company. It's null where the gateway can't say.
• retry_after is the seconds until waiting should help, where the gateway knows. Otherwise it's null, and you back off as you see fit.
• Treat a code you don't know as a refusal, and a state you don't know as not final. New codes may be added; existing ones never change meaning.

The same codes appear elsewhere: in GET /v1/places, for why a place isn't open to your robot now; in notices (booking conflict, directions changed, stop); and in directions that are refused. The guide has more. On the sandbox, the scenario places give closed, outside_hours, approval_declined, device_refused and fire_recall whenever you ask them.

Reason codes

A few codes come from the refusal's own words, which say more: closed (the reason gives the closure's), timeout (it says in which state), gateway_restarted, emergency (which one, and where), fire_recall, and device_refused (what the door or elevator answered). Each has retry true. no_route comes from directions only: every way there is closed to your robot now. other is anything else: read the reason. The rest are in this table, from the gateway's own list.