Errors

Every refusal is application/problem+json (RFC 9457):

{
  "type": "https://updawg.net/problems/insufficient-scope",
  "title": "Not permitted for this token",
  "status": 403,
  "detail": "this API token does not carry the `approve` scope"
}

Branch on type. It is a stable identifier; title and detail are for people and their wording can change. status is always the response’s status.

The types

All under https://updawg.net/problems/:

Status	type	Meaning
400	invalid-request	The request is malformed or a value is out of range. detail says which.
401	unauthenticated	No valid session or token. The same answer whatever the reason: missing, unknown, expired or revoked.
403	insufficient-role	Your role doesn’t allow this. An admin or owner can change your role.
403	insufficient-scope	The token lacks the scope, or this needs a signed-in person. See authentication.
403	plan-required	The organization’s plan doesn’t include this. detail names the plan that does.
403	csrf-token-invalid	Portal sessions only: the X-Updawg-Csrf header is missing or wrong.
404	not-found	No such thing, or it isn’t yours. An organization you don’t belong to answers exactly like one that doesn’t exist.
409	(varies)	The request conflicts with the current state. The type names the reason, for example slug-taken, last-owner, already-approved, wrong-status. detail explains it.
413	payload-too-large	The body is too big.
429	rate-limited	Too many requests. Wait for Retry-After; see rate limits.
503	unavailable	Something the API depends on failed. Try again shortly.

A 409 is worth reading rather than retrying: the same request will meet the same state. A 503 and a 429 are the ones to retry, after a pause.