Errors

Real APIs are inconsistent: a 404 on one route does not look like a 404 on another. Akuma lets you define your own error bodies, reuse them by name, and override them per route.

Built-in defaults

With no configuration, akuma returns these. Every one of them is customizable, keyed by its status code.

Condition	Status	Body
Item id not found	404	`{ "error": "Not found" }`
Non-numeric `:id`	400	`{ "error": "Invalid ID" }`
Wrong method on a path	405	`{ "error": "Method not allowed", ... }`
Database failure	500	`{ "error": "Database error" }`
No route matched	404	`{ "error": "Endpoint not found", ... }`

 A 405 response also carries an Allow header listing the methods the path does support. A 405 is path-level, so it resolves from defaultErrors (not a single endpoint).
 Named errors
 Define reusable error bodies under errors. Each body is the same inline:/schema: shape as any response (almost always inline: for errors).
 errors:
  notFound:
    inline:
      code: not_found
      message: "The resource does not exist"
  noSuchUser:
    inline:
      code: no_such_user
  serverError:
    inline:
      code: server_error
 Server-wide defaults
 Map status codes to errors with defaultErrors. A value is either the name of a catalog entry or a one-off inline body. This also covers the catch-all 404 for any unmatched route.
 defaultErrors:
  404: notFound
  500: serverError
 Per-route overrides
 Give an endpoint its own errors map to model route-to-route differences. Reference a named error, or write a one-off body inline when it is not worth naming.
 endpoints:
  - path: /users/:id
    method: GET
    response:
      schema: User
    errors:
      404: noSuchUser              # this route's 404 differs

  - path: /legacy/:id
    method: GET
    response:
      schema: User
    errors:
      404:
        inline:                    # a one-off, not worth naming
          message: "deprecated and not found"
 Resolution for a given status is: the endpoint's errors, then defaultErrors, then the built-in default. Configure none of it and nothing changes.
 Keep errors in a separate file
 The errors catalog can be a path instead of an inline map, so your error shapes live in their own file and stay out of the main config.
 # akuma.yml
errors: ./errors.yml
 # errors.yml
notFound:   { inline: { code: not_found } }
serverError: { inline: { code: server_error } }
 Common mistakes
 Referencing an error that is not in the catalog
 A named error used in defaultErrors or an endpoint's errors must exist in the errors catalog:
 Error: defaultErrors entry for status 404 references unknown error 'ghost'. Define it under `errors:`.