Errors
Error response format and the status codes the API returns.
The GuideLab API uses conventional HTTP status codes to indicate the result of a request, and returns a consistent JSON envelope for failures.
Error envelope
Errors respond with a JSON body containing an error message and, optionally, a
machine-readable code and a details field with structured context (for
example, field‑level validation issues):
{
"error": "Invalid query parameters",
"details": {
"limit": "Expected number, received string"
}
}| Field | Type | Description |
|---|---|---|
error | string | Human‑readable description of what went wrong. |
code | string? | Stable identifier for a failure a client can act on. |
details | any? | Optional structured details (e.g. validation errors). |
Branch on code, never on the error text, which may change. For example, a
shipment command sent with an outdated expectedVersion fails with 409 and
"code": "shipment_version_stale": reload the shipment and retry.
Status codes
| Status | Meaning |
|---|---|
200 | OK — the request succeeded. |
201 | Created — a new resource was created. |
400 | Bad Request — invalid input (failed validation, malformed body). |
401 | Unauthorized — invalid session or native device credential. |
403 | Forbidden — authenticated, but lacking the required org type/role. |
404 | Not Found — the resource does not exist or isn't in your org. |
409 | Conflict — the request conflicts with current state. |
500 | Internal Server Error — an unexpected error occurred. |
A 401 means the request wasn't authenticated — see
Authentication. A 403 means it was authenticated but the
session's organization type or role isn't permitted for that endpoint.
Validation errors
Request bodies and query parameters are validated with Zod.
When validation fails, the API responds with 400 and includes the offending
fields in details so clients can surface precise messages.