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
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. |
details | any? | Optional structured details (e.g. validation errors). |
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.