Errors

How the Servor API reports errors — typed JSON responses and the status codes 401, 403, 404, 422 and 429, with the cause and fix for each.

When a request can't be fulfilled, the Servor API returns a standard HTTP status code and a typed JSON body. This page shows the shape of an error response and lists every status code you'll encounter, with its cause and how to fix it.

Error shape

Every error is JSON with a human-readable error, a stable machine-readable code, and sometimes a details object with more context:

{
  "error": "Missing required scope: incidents:write",
  "code": "forbidden",
  "details": { "required": "incidents:write" }
}

Match on code in your integration, not on the error text — the message may be reworded, but the code is stable.

Status codes

Status	Meaning	Typical cause
`401`	Unauthorized	Missing, malformed or invalid token.
`403`	Forbidden	Valid token, but it lacks the required scope.
`404`	Not found	The resource doesn't exist, or isn't in your team.
`422`	Unprocessable	The request body failed validation.
`429`	Too many requests	You hit the rate limit.

401 — Unauthorized

The token is missing, malformed, or no longer valid (for example, it was revoked).

Check the header is exactly Authorization: Bearer sv_live_....
Confirm the token wasn't revoked and hasn't been replaced.
Verify it with GET /v1/me — see Authentication.

{ "error": "Invalid or missing token", "code": "unauthorized" }

403 — Forbidden

The token is valid but doesn't carry the scope the endpoint requires. This is the most common error when an integration grows into a new endpoint.

Read details.required to see which scope is missing.
Create a new token with the right scopes — you can't add scopes to an existing token, so issue a replacement and rotate. Open API tokens in Servor.

{
  "error": "Missing required scope: monitors:read",
  "code": "forbidden",
  "details": { "required": "monitors:read" }
}

404 — Not found

The resource id doesn't exist, or it belongs to a different team than your token. A token only ever sees its own team's data, so a valid id from another team still returns 404.

Double-check the id and that it belongs to your team.
Confirm the resource wasn't deleted in the dashboard.

{ "error": "Server not found", "code": "not_found" }

422 — Unprocessable entity

The request reached a valid endpoint but the body failed validation — a missing required field, a wrong type, or an invalid value. You'll mostly see this on the incidents:write endpoints.

Read details for the field-level problems and fix the payload.
Check required fields (for example, an incident needs a title and status).

{
  "error": "Validation failed",
  "code": "validation_error",
  "details": { "title": "Required", "status": "Invalid value" }
}

429 — Too many requests

You exceeded the per-token rate limit. The response includes a retry-after header with how many seconds to wait.

Read retry-after and back off for exactly that long, then retry.
See rate limits for a ready-made retry pattern.

{ "error": "Rate limit exceeded", "code": "rate_limited" }

You won't see 423 on read tokens

A 423 (vault locked) can only come from actions that require an unlocked vault in the browser — command execution. The public API never executes commands and has no such endpoint, so read and incident-automation tokens won't encounter it. Vault unlocking is a dashboard concern — see unlock your vault.

Handling errors well

Branch on code, not the message. Codes are stable; wording can change.
Treat 429 as flow control. Back off and retry rather than failing hard.
Fail loudly on 401/403. These mean a token or scope problem you must fix — rotate the token or grant the right scope.
Log details on 422. It tells you exactly which field to correct.