rails-problem

Rails API Errors with problem

Conventions for answering errors from a Rails API as RFC 9457 problem documents with the problem gem. Project-specific conventions (CLAUDE.md, docs/) always take priority.

problem works on its own: error classes declare type, status and title with its DSL, and nothing else is needed. An app whose schema lives in .proto files can instead take those from a protobuf enum through protobufable; the sections below cover both, and /sorah-guides:rails-protobuf covers the enum catalogue and answering problems over Connect RPC. Application examples come from ruby-no-kai/sponsor-app, which uses the protobuf form.

The model

An error is a class. Its type, status and title belong to the class and are declared once; only detail (and machine-readable extras) vary per occurrence. A controller concern renders every such class, and an exceptions app renders whatever escapes before a controller runs, so every failure a client sees has one shape.

• Clients dispatch on type. A title can be reworded freely; a type is a published identifier and is append-only.
• The status is a property of the problem type, not of the code path that raised it. Two failures needing different statuses are two types.
• detail is prose for a person, specific to the occurrence. Anything a client acts on goes in an extension member, never parsed out of detail.

Error classes

One base class carries the mixin; every error is a subclass that declares what differs. Keep them together in app/models/errors.rb (a module Errors), with a one-line doc comment per class saying when it is raised.

Plain declarations

Without protobuf, the base includes Problem::Detailable (or Problem::I18nable for translated titles, which brings Detailable with it), and each class declares its members with the DSL:

# app/models/errors.rb
module Errors
  # An error the API answers as a problem.
  class ApiError < StandardError
    include Problem::Detailable
  end

  # The resource the request names does not exist.
  class NotFound < ApiError
    type "not-found"
    status 404
    title "Not Found"
  end

  # The resource is not in a state that allows the request.
  class FailedPrecondition < ApiError
    type "failed-precondition"
    status 412
    title "Failed Precondition"
  end
end