restful-api-guidelines/models/problem-1.0.1.yaml at 633e5072f1db79e4476e0cd1571ba1fa90d86adb · zalando/restful-api-guidelines · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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
Problem:
  type: object
  properties:
    type:
      type: string
      format: uri-reference
      description: >
        An optional member, URI identifying the problem type, typically more
        specific than the HTTP status code. In many cases, an error code can be
        placed in the type property. It may support automated client decisions
        in certain failure modes. If the type doesn’t provide additional
        information, it can be omitted (defaulting to `"about:blank"`).
      default: 'about:blank'
      examples:
        - 'https://example.com/errors/invalid-parameter'
        - 'https://example.com/errors/ERR12345'  # with error code
    title:
      type: string
      description: >
        A short, human-readable summary of the problem type. It *SHOULD NOT*
        change from occurrence to occurrence of the problem. Written in English
        and readable for engineers, usually not suited for non-technical
        stakeholders and not localized.
      example: 'Invalid parameter'
    status:
      type: integer
      format: int32
      description: >
        The HTTP status code generated by the origin server for this occurrence
        of the problem.
      minimum: 100
      maximum: 600
      exclusiveMaximum: true
      example: 400
    detail:
      type: string
      description: >
        A human readable explanation specific to this occurrence of the
        problem that is helpful to locate the problem and give advice on how
        to proceed. Written in English and readable for engineers, usually not
        suited for non technical stakeholders and not localized.
      example: 'The \"color\" parameter is invalid'
    instance:
      type: string
      format: uri-reference
      description: >
        A URI reference that identifies the specific occurrence of the problem,
        e.g. by adding a fragment identifier or sub-path to the problem type.
        This field should serve the purpose of defining a clear error instance
        from which a developer can determine the source location of the error.
        Additionally, it may include relevant contextual information, such as
        parameters associated with the error and optionally `Flow-ID` for
        debugging purposes.
      example: '/errors/12345'