Error Messages

In case of an error, the RIPE Atlas APIs will return an error response with an unsuccessful HTTP status code and a JSON object describing what is wrong with the request.

Example response

{
  "error": {
    "status": 400,
    "errors": [
      {
        "source": {
          "pointer": "/definitions/0/af"
        },
        "detail": "This field is required."
      }
    ],
    "code": 102,
    "detail": "There were problems with your request",
    "title": "Bad Request"
  }
}

Fields

• status (integer): Mirrors the HTTP status code of the response code
• code (integer): [deprecated]
• detail (string): A human-readable overview of the error
• title (string): A short human-readable string with the type of error
• errors (array): [optional] A list of error objects describing the errors in detail

Error objects

In some cases, the API will provide more detailed feedback on errors - especially when they relate to incorrect user input. These error objects are modelled on the errors from the JSON API format (opens new window), but aren't intended to be strictly compliant.

• source (string): An object containing either:
  • pointer (string): An RFC6901 JSON Pointer (opens new window) referring to the place in the input JSON which caused the error, or
  • parameter (string): The URL parameter which caused the error
• detail (string): A human-readable description of the error

In future, the error format may be expanded in a backwards-compatible way to, for example, include machine-readable error codes.

Warning objects

In a limited number of cases, the RIPE Atlas API might reply with warning messages. Such messages indicate that, although the request was not blocked and the API was still able to do some of the work, a problem occurred when processing the request. This section explains the format of these warnings. To get more information about when warnings are returned, you can read this documentation page.

Warning objects are the same as error objects in that they contain both source and detail attributes. In those cases where warnings are returned, they will be added as a warnings list inside the successful JSON response.

The following is a response example containing the warnings list:

{
    // successful response containing a 200 HTTP status code
    // it also contains a warnings element that indicates it 
    // encountered some problems
    "warnings" : [
    	{
            "source": {
            	"pointer": "/1/value"  // item at position #1 inside the request triggered the warning
            },
            "detail": 'Invalid area defined.  It must be one of: "WW", "West", "North-Central", "South-Central", "North-East", "South-East"'
      }
    ]
}