Errors

/api/v1/*: Problem Details

Errors from the v1 API are RFC 7807 Problem Details with Content-Type: application/problem+json. The members are:

• type: a stable URL, https://api.aldursvottun.is/errors/<slug>. Branch on this (or on status), not on the text.
• title: usually the HTTP reason phrase, such as "Not Found". Some types have their own, such as "Organization Not Active" for tenant-inactive.
• status: the HTTP status code.
• detail: a human-readable explanation. Left out on 500 and 503.
• instance: the request path, on errors raised before the endpoint runs (authentication and validation). Not always present.
• traceId: our id for this request, the same value as the X-Trace-Id response header. On every Problem Details error.
• Extension members on some errors: errors on 422; retryAfterSeconds and reason on 429; retryAfterSeconds on 503.

{
  "type": "https://api.aldursvottun.is/errors/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired access token",
  "instance": "/api/v1/devices",
  "traceId": "3f1c9a52-7d4e-4b0a-9c1e-2a6f8d0b5e17"
}

Trace ID

Every /api/v1/* response, success or error, carries an X-Trace-Id header (a UUID; browsers can read it, it is in Access-Control-Expose-Headers). Problem Details bodies repeat it as traceId. We generate it for each request; an X-Trace-Id or X-Request-Id header you send is ignored.

Log it with your own request. When you contact support about a failed request, especially a 500 or 503, quote the traceId: it is how we find that request in our logs.

Validation errors (422)

A 422 lists every failing field in errors, each with field (a dotted path, or (root)) and message. Query parameters are validated the same way.

{
  "type": "https://api.aldursvottun.is/errors/validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request body failed validation",
  "instance": "/api/v1/verifications",
  "errors": [
    { "field": "requiredAge", "message": "Number must be less than or equal to 150" }
  ]
}

Status codes

The slug is the last part of type.

A verification that runs but doesn't pass is not an error: it returns 200 with "result": "fail". See Verification. The 429 body is shown on Rate limits.

/api/oauth/*: OAuth errors

POST /api/oauth/token and POST /api/oauth/device_authorization answer in the OAuth 2.0 format (RFC 6749 §5.2), with Content-Type: application/json. error is always present; error_description is sometimes present. Device code polls leave out error_description, and authorization_pending carries the poll interval in seconds.

{
  "error": "invalid_request",
  "error_description": "Missing grant_type (the body must be application/x-www-form-urlencoded)"
}

The token grants are described in Authentication and Device authentication.

/api/devices/*: legacy format

The device endpoints outside /api/v1 return { error, code }. error is a human-readable message; branch on code. /api/devices/validate adds "valid": false.

{
  "valid": false,
  "error": "Organization is suspended",
  "code": "TENANT_SUSPENDED"
}

Removed and unknown endpoints

• /api/devices/link and /api/devices/link/claim return 410 Gone with { "error": "legacy_endpoint_removed", "message": "..." }. Use the device flow instead.
• A path under /api/ that doesn't exist returns 404 with { "error": "Not found" }.