Errors & rate limits
A predictable error envelope, the status codes you’ll see, and per-key limits.
Error envelope
Errors return the relevant HTTP status and a JSON body with a human-readable message:
{ "error": "Missing required scope: records:write" }Status codes
400 — invalid body or parameters · 401 — missing/invalid key · 403 — missing scope · 404 — not found · 409 — conflict (a duplicate work order was detected, or an asset tag already exists) · 422 — unprocessable (e.g. an invalid status transition, or a required reason is missing) · 429 — rate limited · 500 — server error.
The duplicate check (409)
When you create a work order that looks like an existing one, the API returns 409 with a candidates array instead of silently creating a duplicate. Review them, then resubmit with "confirmCreate": true to create anyway:
{
"error": "duplicate_check",
"message": "2 possible duplicates found — review them or pass confirmCreate=true to create anyway.",
"candidates": [ { "id": "WO-000188", ... } ]
}Rate limits
Each key is rate-limited (default 60 requests per minute, configurable per key). Exceeding the limit returns 429 — back off and retry. Design integrations to spread bulk work over time rather than bursting.