Errors

This section provides info about types of errors you can encounter when making requests to the GoodData.CN API including description of error response payload format you can use for better understanding of problem or during building robust error handling in your API integration.

Error types

When you encounter error during calling GoodData.CN API it can be typically categorized to either error on caller side - client error, on called side - server error or somewhere in between - on network level.

Client error

Errors caused by client are always returned with HTTP response status code of 4xx. Client-side errors are signalized by specific status coded - like 401 for invalid authentication or 404 for accessing non-existing resource. Generic errors (400) often contains detailed description giving guidance what went wrong - you can find it in the response payload under “description” key.

Input Validation errors

There are various types of validations on the API - if resource exists, if it supports specific HTTP method, if it’s able to consume or produce specific media type and of course if contains valid payload.

Most complex output in details section of error response payload can be produced in case if invalid request payload. Note that in order to investigate the problem in some complex hierarchies of OpenAPI schemas (which are used for validation) it’s recommended to use API reference.

Server error

Errors caused by problem on server are always returned with HTTP response status code of 5xx. This type of error cannot be fixed on client side and client have to wait until GoodData.CN API will be in operational state again. In case of server errors no specific details are provided to client but (same as in case of client errors) the traceId key always appear in response payload. Please use it for further investigation or when you ask for help in community because it’s always uniquely bounded to the problematic request (in the application logs).

Network error

Errors caused by problem during transport on network layer. Typical example 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 single format specified by RFC 7807. This means that on client side you can be always sure how to the problem response can be deserialized.

RFC 7807 is used as a standard format for returning problem details from 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 error.

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

• Error responses will have each of the following keys:

  • type, a unique URI for the error type, pointing to human-readable documentation of 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, carrying the HTTP status code
  • traceId, used for problem reporting or investigation (logged along the request, can be used for error investigation), 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"
}