Module: Apiwork::ErrorCode

Defined in:
lib/apiwork/error_code.rb,
lib/apiwork/error_code/registry.rb,
lib/apiwork/error_code/definition.rb

Defined Under Namespace

Classes: Definition, Registry

Constant Summary collapse

DEFAULTS = 
{
  bad_gateway: {
    status: 502,
  },
  bad_request: {
    status: 400,
  },
  conflict: {
    status: 409,
  },
  forbidden: {
    status: 403,
  },
  gateway_timeout: {
    status: 504,
  },
  gone: {
    status: 410,
  },
  internal_server_error: {
    status: 500,
  },
  locked: {
    status: 423,
  },
  method_not_allowed: {
    status: 405,
  },
  not_acceptable: {
    status: 406,
  },
  not_found: {
    attach_path: true,
    status: 404,
  },
  not_implemented: {
    status: 501,
  },
  payment_required: {
    status: 402,
  },
  precondition_failed: {
    status: 412,
  },
  request_timeout: {
    status: 408,
  },
  service_unavailable: {
    status: 503,
  },
  too_many_requests: {
    status: 429,
  },
  unauthorized: {
    status: 401,
  },
  unprocessable_entity: {
    status: 422,
  },
  unsupported_media_type: {
    status: 415,
  },
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#key ⇒ Symbol (readonly)

The key for this error code.

Returns:

  • (Symbol) 


28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/apiwork/error_code/definition.rb', line 28

Definition = Struct.new(:key, :status, :attach_path, keyword_init: true) do
  # @api public
  # Whether this error code attaches the request path.
  #
  # @return [Boolean]
  def attach_path?
    attach_path
  end

  # @api public
  # The description for this error code.
  #
  # @param locale_key [String, nil] (nil)
  #   The I18n namespace for API-specific translations.
  # @return [String]
  #
  # @example
  #   error_code = Apiwork::ErrorCode.find!(:not_found)
  #   error_code.description # => "Not Found"
  #   error_code.description(locale_key: 'api/v1') # apiwork.apis.api/v1.error_codes.not_found.description
  def description(locale_key: nil)
    if locale_key
      api_key = :"apiwork.apis.#{locale_key}.error_codes.#{key}.description"
      result = I18n.translate(api_key, default: nil)
      return result if result
    end

    global_key = :"apiwork.error_codes.#{key}.description"
    result = I18n.translate(global_key, default: nil)
    return result if result

    key.to_s.titleize
  end
end

#status ⇒ Integer (readonly)

The status for this error code.

Returns:

  • (Integer) 


28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/apiwork/error_code/definition.rb', line 28

Definition = Struct.new(:key, :status, :attach_path, keyword_init: true) do
  # @api public
  # Whether this error code attaches the request path.
  #
  # @return [Boolean]
  def attach_path?
    attach_path
  end

  # @api public
  # The description for this error code.
  #
  # @param locale_key [String, nil] (nil)
  #   The I18n namespace for API-specific translations.
  # @return [String]
  #
  # @example
  #   error_code = Apiwork::ErrorCode.find!(:not_found)
  #   error_code.description # => "Not Found"
  #   error_code.description(locale_key: 'api/v1') # apiwork.apis.api/v1.error_codes.not_found.description
  def description(locale_key: nil)
    if locale_key
      api_key = :"apiwork.apis.#{locale_key}.error_codes.#{key}.description"
      result = I18n.translate(api_key, default: nil)
      return result if result
    end

    global_key = :"apiwork.error_codes.#{key}.description"
    result = I18n.translate(global_key, default: nil)
    return result if result

    key.to_s.titleize
  end
end

Class Method Details

.find(key) ⇒ ErrorCode::Definition?

Finds an error code by key.

Examples:

Apiwork::ErrorCode.find(:not_found)

Parameters:

  • key (Symbol) —

    The error code key.

Returns:

See Also:



114
115
116
117
118
119
120
121
 
# File 'lib/apiwork/error_code.rb', line 114

delegate :clear!,
:exists?,
:find,
:find!,
:keys,
:register,
:values,
to: Registry

.find!(key) ⇒ ErrorCode::Definition

Finds an error code by key.

Examples:

Apiwork::ErrorCode.find!(:not_found)

Parameters:

  • key (Symbol) —

    The error code key.

Returns:

Raises:

  • (KeyError) —

    if the error code is not found

See Also:



114
115
116
117
118
119
120
121
 
# File 'lib/apiwork/error_code.rb', line 114

delegate :clear!,
:exists?,
:find,
:find!,
:keys,
:register,
:values,
to: Registry

.key_for_status(status) ⇒ Object 



123
124
125
 
# File 'lib/apiwork/error_code.rb', line 123

def key_for_status(status)
  DEFAULTS.find { |_key, config| config[:status] == status }&.first
end

.register(key, attach_path: false, status:) ⇒ ErrorCode::Definition

Registers a custom error code for use in API responses.

Error codes are used with ‘raises` declarations and `expose_error` in controllers. Built-in codes (400-504) are pre-registered.

Examples:

Register custom error code

Apiwork::ErrorCode.register :resource_locked, status: 423

With path attachment

Apiwork::ErrorCode.register :not_found, status: 404, attach_path: true

Parameters:

  • key (Symbol) —

    The unique identifier for the error code.

  • attach_path (Boolean) (defaults to: false) —

    (false) Include request path in error response.

  • status (Integer) —

    The HTTP status code (must be 400-599).

Returns:

Raises:

  • (ArgumentError) —

    if status is outside 400-599 range

See Also:



114
115
116
117
118
119
120
121
 
# File 'lib/apiwork/error_code.rb', line 114

delegate :clear!,
:exists?,
:find,
:find!,
:keys,
:register,
:values,
to: Registry

.register_defaults! ⇒ Object 



127
128
129
 
# File 'lib/apiwork/error_code.rb', line 127

def register_defaults!
  DEFAULTS.each { |key, options| register(key, **options) }
end