API Design

Error Responses

All error responses are returned with Content-Type: application/problem+json.

We have rolled our own implementation inspired by:

  • RFC-7807 [1]

  • Micronaut Problem JSON [2]

  • Zalando Problem [3]

In addition to the standard members, we have added a couple of extension members:

  • code: numeric code

  • info: key-value map

  • trace: object with traceId and spanId

Example Problems

validation error 
{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Unsupported file type",
    "instance": null,
    "code": 2000,
    "info": {
        "supportedMediaTypes": ["text/csv"],
        "filename": "build.gradle"
    },
    "trace": {
        "spanId": "3b190a772d4eef2d",
        "traceId": "61668ee8072e1fdf3b190a772d4eef2d",
    }
}
constraint violations 
{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 400,
    "detail": "Constraint violation",
    "instance": null,
    "code": 1000,
    "info": {
        "violations": [
            {
                "field": "createTrialBalance.cmd.accounts",
                "message": "must not be empty"
            },
            {
                "field": "createTrialBalance.cmd.year",
                "message": "must not be null"
            }
        ]
    },
    "trace": null
}