API Errors

This section provides details 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, which should help you better understand API issues or build robust error handling for your API integration.

Error Types

If you encounter an error while calling the GoodData API, it can be typically categorized either as an error on the caller’s side (client error), on the recipient’s side (server error), or 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 contain detailed descriptions that identify what went wrong. You can find these descriptions in the response payload under the “description” key.

Input Validation Errors

The API runs multiple validation checks. These check, for example:

• The existence of the resource.
• The resource support for a specific HTTP method.
• The ability of the resource to consume or produce a specific media type.
• 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. To investigate issues with some of the more complex hierarchies of OpenAPI schemas, use the API reference.

Server Errors

Errors caused by an issue on the server’s side are always returned with the HTTP response status code of 5xx.

Unfortunately, this type of error cannot be fixed by the client. Server errors provide no specific details to the client, but like client errors, the traceId key always appears in the response payload. Because the traceId is always uniquely bound to the problematic request in the application logs, it helps us identify, investigate, and resolve issues as quickly as possible. If you decide to contact our support team, provide us with this ID.

Network Errors

These are errors caused by a problem during communication in 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

Error 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 error response.

RFC 7807 is used as the standard format for returning the details about issues 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 are of the Content-Type application/problem+json

• Error responses 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 error 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 status code 429 — Too Many Requests

You have exceeded the maximum number of API requests allowed in a fixed time window. This rate limit protects our server infrastructure. If you are getting this error:

• Wait at least one minute and then try the request again. The servers may just be under an unexpected amount of strain.
• If you repeatedly encounter this error, review your code to ensure you are not unintentionally making excessive API calls (for example, retry loops or inefficient polling).
• If the issue persists after optimizing your calls, contact GoodData support.

Normal use of the GoodData API should not hit this limit.

Rate limit headers

When you receive a 429 Too Many Requests response, the API includes headers to help you understand and adjust your request rate:

Use these headers to throttle or pause requests until the limit resets.

“HTTP/2 stream 0 was not closed cleanly”

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)

This is likely caused by a bug in curl itself.

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.