Errors

Learn how errors are communicated

This section provides info about the types of errors you can encounter when making requests to the GoodData API. This includes the description of the error response payload format so you can better understand problems or build robust error handling for your API integration.

Error Types

When you encounter an error while calling GoodData API, it can be typically categorized as either an error on the caller side (client error), an error on the called side (server error), or an error that is somewhere in between (network level).

Client Errors

Errors caused by the client are always returned with an HTTP response status code of 4xx. For example, 401 for invalid authentication or 404 for accessing a non-existing resource. Generic errors (400) often contains detailed descriptions that identify what went wrong. You can find these descriptions in the response payload under “description” key.

Input Validation Errors

There are different validation checks that occur for the API. For example:

  • There is a check to validate the existence of the resource.
  • There is a check to validate that the resource supports a specific HTTP method.
  • There is a check to validate that the resource is able to consume or produce a specific media type.
  • There is a check to validate the payload itself.

The most complex output in the details section of the error response payload is produced when a request has an invalid payload. In order to investigate problems in some of the more complex hierarchies of OpenAPI schemas, it’s recommended to use the API reference.

Server Errors

Errors caused by a problem on the server are always returned with the HTTP response status code of 5xx. This type of error cannot be fixed on the client side, and the client has to wait until the GoodData API returns to an operational state. Server errors provide no specific details to the client, but like client errors, the traceId key always appears in the response payload. Please use it for further investigation or when you ask for help in the GoodData community. The traceId is always uniquely bound to the problematic request in the application logs.

Network Errors

These are errors caused by a problem during transport on the network layer. Typical examples of network errors are connection or timeout errors. The best way how to deal with these type of errors is to retry the request.

Error Response Payload

Errors details are always communicated in the single format specified by RFC 7807. This means that on the client side you can determine how to deserialize the problem response.

RFC 7807 is used as the standard format for returning the details about problems encountered with HTTP APIs. It specifies the following:

  • Error responses MUST use standard HTTP status codes in the 400 or 500 range to detail the general category of the error.

  • Error responses will be of the Content-Type application/problem+json

  • Error responses will each have the following keys:

    • type
      A unique URI for the error type. This points to the human-readable documentation for that given type. When this member is not present, its value is assumed to be “about:blank”.
    • detail
      A human-readable description of the specific error.
    • title
      A short, human-readable title for the general error type; the title should not change for given types.
    • status
      The HTTP status code.
    • traceId
      An identification number used for problem reporting or investigation. This is logged with the request and is always returned

Example of error response body:

{
  "title": "Invalid format for metric.",
  "detail": "Metric format '#,x1' is invalid, please try different one.",
  "status": 400,
  "traceId": "d6as1n21N21w1"
}

Common Errors

This section contains a reference for commonly encountered problems with the API, and instructions on how to fix them, or work around them.

“HTTP/2 stream 0 was not closed cleanly”

Error

If you use MacOS and an older version of curl, you may encounter the following error:

curl: (92) HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1)

Diagnosis

This is likely caused by a bug in curl itself.

Solution

Try one of the following:

  • Update to the most recent stable version of curl.
  • Or force HTTP/1.1 by adding option --http1.1 to your curl command.
Conventions
Filter Entities