API Errors

Roster REST errors use strict RFC 9457 Problem Details. Error responses return Content-Type: application/problem+json and do not include legacy error, message, or raw validator fields.

This is the canonical shape:

{
  "type": "/api/v1/problems/validation_error",
  "title": "Validation failed",
  "status": 422,
  "detail": "Project request validation failed.",
  "instance": "urn:roster:request:req_...",
  "request_id": "req_...",
  "invalid_params": [
    { "name": "/name", "reason": "Too small: expected string to have >=1 characters" }
  ]
}

Fields

| Field | Meaning | | ---------------- | ---------------------------------------------------------------------------- | | type | Stable machine identifier for the problem class. | | title | Stable short title for the problem class. | | status | HTTP status code mirrored in the body. | | detail | Safe occurrence-specific explanation. | | instance | Unique occurrence URI based on request_id. | | request_id | Request correlation ID, generated by Roster or accepted from x-request-id. | | invalid_params | Validation-only array of JSON Pointer names and safe reasons. |

Status Codes

| Status | Problem type | When it is used | | ------ | ----------------------------------------- | --------------------------------------------------------------- | | 400 | /api/v1/problems/invalid_request | Malformed JSON or malformed query syntax. | | 401 | /api/v1/problems/invalid_token | Missing, malformed, expired, revoked, or inactive credentials. | | 401 | /api/v1/problems/unsupported_auth_mode | The bearer credential type is not supported for REST. | | 403 | /api/v1/problems/insufficient_scope | The credential is valid but lacks the required api:* scope. | | 403 | /api/v1/problems/forbidden | The identity lacks platform or resource authorization. | | 404 | /api/v1/problems/not_found | The resource is absent or intentionally hidden from the caller. | | 405 | /api/v1/problems/method_not_allowed | The endpoint does not support the HTTP method. | | 409 | /api/v1/problems/conflict | The request conflicts with existing state. | | 413 | /api/v1/problems/payload_too_large | The JSON body exceeds the REST body limit. | | 415 | /api/v1/problems/unsupported_media_type | A JSON body endpoint received a non-JSON content type. | | 422 | /api/v1/problems/validation_error | Parsed input fails schema or business validation. | | 429 | /api/v1/problems/rate_limited | Rate limit exceeded. | | 500 | /api/v1/problems/server_error | Unexpected server failure with a safe generic detail. |

Examples

Missing credentials:

{
  "type": "/api/v1/problems/invalid_token",
  "title": "Invalid token",
  "status": 401,
  "detail": "Missing Authorization bearer token.",
  "instance": "urn:roster:request:req_...",
  "request_id": "req_..."
}

Missing scope:

{
  "type": "/api/v1/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "API key is missing api:participants:write.",
  "instance": "urn:roster:request:req_...",
  "request_id": "req_..."
}

Rate limiting:

{
  "type": "/api/v1/problems/rate_limited",
  "title": "Rate limited",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "instance": "urn:roster:request:req_...",
  "request_id": "req_...",
  "retry_after_seconds": 58
}

Rate limit responses also include Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Problem Details is defined by RFC 9457. HTTP status semantics follow RFC 9110 and the IANA HTTP status code registry.