Troubleshooting on API error

Our backend services respond on non 2xx status code with the JSON schema described in this page. In case of an error, you should use the curl -v command to send test requests against an API and provide us the information from the log.

Error Model

The JSON schema of the response payload is as following:

Error JSON Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "code": {
      "type": "integer"
    },
    "timestamp": {
      "type": "string"
    },
    "errors": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "field": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "message",
          ]
        }
      ]
    }
  },
  "required": [
    "status",
    "code",
    "timestamp",
    "errors"
  ]
}

Sample Error Payload

{
  "status": "BAD_REQUEST",
  "code": 400,
  "timestamp": "2022-09-20T12:01:51.000000Z",
  "errors": [
    {
        "type": "MISSING_PARAMETER",
        "message": "Validation error: latitude must be double.",
        "field": "latitude"
    },
    {
        "type": "MISSING_PARAMETER",
        "message": "Validation error: longitude must be double.",
        "field": "longitude"
    }
  ]
}

Error Code

The code field in the payload is the HTTP status code and should be the same as the response status code of the request to avoid confusion. In some use cases, special codes beside those HTTP status code are documented in the OpenAPI of a service.

Error Status

The status field is the additional information about the status code. It is related to the HTTP status code.

Timestamp

The timestamp field describes the time of given incident in ISO 8601 format.

Error Details

The errors field is a list of errors providing the information about cause of the given situation. For each error in the list, the type field is documented in the OpenAPI of each service. Together with the error message in the message field, it should help API clients to understand and solve the problem quickly. The field field points out the specific problem of your request.