Error handling

Standard HTTP error codes

All platform service APIs mainly (but not only) use these HTTP status codes. Additional status or standard codes are used differently and documented in the respective service's Swagger UI.

Error Status Code	Description
400 - Bad Request	The request syntax was corrupt. It's also the default fallback code to transport an application-level error if no specific error code is available (for example, the request was valid, but the application logic refused to execute it due to some application restriction like a quota).
401 - Unauthorized	The request was rejected because the client needs to be authenticated first.
403 - Forbidden	The request was rejected because the (authenticated) client didn't have the necessary permissions. See Errors for the details in the error response.
404 - Not Found	The requested resource wasn't found (it never existed).
409 - Conflict	The write operation failed because the "optimistic locking" strategy detected a conflict.
410 - Gone	The requested resource wasn't found, although it existed some time ago.
429 - Too Many Requests	The client sent too many requests at a certain time.
500 - Internal Server Error	Unspecified server error (typically caused by internal problems like exceptions).
501 - Not Implemented	The API doesn't support the operation.
503 - Service Unavailable	Service is temporary unavailable.

Errors

Error responses are always returned in an error envelope like this:

{
  "error": {
    "code": "error code",
    "message": "error message"
  }
}

• code is set to the HTTP response code or an API-specific error code documented in the service APIs Swagger UI.
• message is a brief description of the error that occurred

You can add additional details about each error in a details field. This section conveys additional information about the error, for example, which query parameter violated a precondition. The details field contains fields to describe the error further.

These are commonly used fields in the details object:

• errorRef is a uuid string (see rfc-4122) and represents a reference of the error into e.g., the log file of the service.
• traceId is a string containing a 32-character hex integer value.
• errorCode is a string value representing more detailed error information than the HTTP response code alone.
• constraintViolations is an array of ConstraintViolation objects.
  • A ConstraintViolation contains information about an input parameter (path, query, or request body) that violated some validation rule of the service API and caused the error.
    • ConstraintViolation always contains a field message describing the error.
    • ConstraintViolation may contain a separate field, parameterLocation, which describes the general location of the violating parameter (query parameter, request body, etc.)
    • ConstraintViolation may contain a separate field, path, which refers to the violating parameter within the parameterLocation.
    • ConstraintViolation may contain additional fields further describing the error.
• missingScopes must be set if the API returns a 403 - Forbidden response.
  • missingScopes is an array of strings containing a complete list of missing IAM scopes necessary to execute the request successfully.

Examples

Following are some examples of error responses.

• Error response with details object.

{
  "error": {
    "code": 400,
    "message": "Constraints violated.",
    "details": {
      "errorRef": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "traceId": "99633483d17779d7c81141f50dbc2a49",
      "errorCode": "InvalidPaginationToken",
      "constraintViolations": [
        {
          "path": "detectionRules[0].filterConfig.pattern",
          "message": "may not be null",
          "parameterLocation": "PAYLOAD_BODY"
        }
      ]
    }
  }
}

• Error response with missingScopes.

{
  "error": {
    "code": 403,
    "message": "Insufficient permissions.",
    "details": {
      "missingScopes": ["document:documents:read", "state:app-states:write"]
    }
  }
}

Warnings

Sometimes a response may contain warning information although the request was successful. It may happen when some data in the request payload was missing and replaced with default values.

Warnings are optional, but if a response contains warnings, they're returned as the first field in the response body, named warnings. It includes an array of potential warning objects. Each warning object has at least a string message field with the warning message.

A details field may add additional details about each warning. This section conveys additional information about the warning, for example, which query parameter violated a precondition. The details may contain any fields to describe the warning further.

These are commonly used fields in the details object:

• warningRef is a uuid string (see rfc-4122) and represents a reference of the warning into e.g., the log file of the service.
• traceId is a string containing a 32-character hex integer value.
• constraintViolations is an array of ConstraintViolation objects.
  • A ConstraintViolation contains information about an input parameter (path, query, or request body) that violated some validation rule of the service API and caused the warning.
    • ConstraintViolation always contains a field message describing the warning.
    • ConstraintViolation may contain a separate field, parameterLocation, which describes the general location of the violating parameter (query parameter, request body, etc.)
    • ConstraintViolation may contain a separate field path that refers to the violating parameter within the parameterLocation.
    • ConstraintViolation may contain additional fields further describing the warning.

Example

{
  "warnings": [
    {
      "message": "caffeine saturation is low",
      "details": {
        "warningRef": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
        "traceId": "99633483d17779d7c81141f50dbc2a49",
        "constraintViolations": [
          {
            "path": "dynatrace.employee",
            "message": "Caffeine is getting low! Grab a cappuccino in the Dynatrace cafeteria!",
            "parameterLocation": "DYNATRACE_OFFICE"
          }
        ]
      }
    }
  ],
  "items": [
    {
      "latestSchemaVersion": "1.4.2",
      "schemaId": "builtin:anomaly.infrastructure",
      "displayName": "Anomaly Detection for Infrastructure"
    }
  ],
  "totalCount": 1
}

Rate limiting (throttling)

Services may decide to reject request execution if it's overloaded or to guarantee fair request execution distribution across multiple customer environments.

If a service throttles a request it returns:

• HTTP 429 - Too Many Requests if the throttling was caused by the client.
• HTTP 503 - Service Unavailable if the service is generally overloaded or is unable to determine if overloading is caused by client.

In both cases the service sets the retry-after header with the number of seconds to wait until the next retry. The error response also includes the time until the next retry in the field retryAfterSeconds in seconds.

It may also include details about the violated constraint in the field details.

Example

{
  "error": {
    "code": 503,
    "message": "service is overloaded",
    "retryAfterSeconds": 3,
    "details": "service is busy, good luck next time!"
  }
}