Error Handling

All errors use RFC 9457 Problem Details format (ADR-0015).

Error Response Format

{
  "type": "https://api.opentabletop.org/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "No game found with slug 'nonexistent-game'",
  "instance": "/v1/games/nonexistent-game"
}

Fields

FieldTypeRequiredDescription
typestring (URI)YesError type identifier
titlestringYesHuman-readable summary
statusintegerYesHTTP status code
detailstringNoHuman-readable explanation specific to this occurrence
instancestring (URI)NoURI of the request that caused the error
errorsarrayNoValidation error details (see below)

Validation Errors

When request parameters fail validation, the response includes an errors array:

{
  "type": "https://api.opentabletop.org/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/games?weight_min=6.0",
  "errors": [
    {
      "field": "weight_min",
      "message": "must be between 1.0 and 5.0",
      "value": "6.0"
    }
  ]
}

Error Types

Type URIStatusMeaning
.../errors/not-found404Resource does not exist
.../errors/validation400Request parameters invalid
.../errors/rate-limited429Rate limit exceeded
.../errors/unauthorized401API key required but not provided
.../errors/forbidden403API key lacks permission
.../errors/internal500Server error

Rate Limit Errors

Rate limit responses include standard headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710288000
Retry-After: 45

{
  "type": "https://api.opentabletop.org/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 60 requests per minute"
}