Errors

Databricks REST APIs use conventional HTTP status codes to signal the outcome of a request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a request that failed given the information provided (for example, a required parameter was missing, or the caller lacks permission). Codes in the 5xx range indicate an error on the Databricks side; these are rare.

When a request fails, the response body is an error object: a machine-readable error_code, a human-readable message, and an optional array of structured details. The same shape is returned by every Databricks service, so a single error handler works across all APIs.

{
  "error_code": "NOT_FOUND",
  "message": "Job 123 does not exist.",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.RequestInfo",
      "request_id": "01ef9a2c-...-d2b1"
    }
  ]
}

The error object

Attribute	Type	Description
error_code	string	A stable, machine-readable code identifying the error. Branch on this value rather than on the HTTP status or message text. Some legacy endpoints return the HTTP status code here as an integer instead of a string; treat a non-string value as absent and fall back to the HTTP status.
message	string	A human-readable explanation of what went wrong, suitable for logs and for surfacing to users. Treat it as informational: wording can change at any time, so do not parse it.
details	array	Optional. Zero or more structured detail objects giving machine-readable context for the error. Each entry is tagged with an @type field identifying its schema. See Error details.

Error codes

The error_code field provides a finer-grained, machine-readable classification of a failure than the HTTP status. Every error_code maps to a single HTTP status, while one HTTP status can cover several codes. Prefer the error_code over the HTTP status when handling errors programmatically. Treat each error_code as a stable string, and route any code you don't recognize to a default branch. The codes most commonly returned across Databricks APIs are listed below.

error_code	HTTP status	Description
INVALID_PARAMETER_VALUE	400	A supplied parameter value was invalid.
BAD_REQUEST	400	The request was invalid for a reason not tied to a single parameter.
UNAUTHENTICATED	401	The request has no valid authentication credentials.
PERMISSION_DENIED	403	The caller is not authorized to perform the operation.
NOT_FOUND	404	The referenced resource does not exist.
ENDPOINT_NOT_FOUND	404	The requested API endpoint does not exist.
ALREADY_EXISTS	409	A resource with the same identity already exists.
ABORTED	409	The operation was aborted, typically due to a concurrent modification.
RESOURCE_EXHAUSTED	429	A rate limit or resource quota was exceeded.
INTERNAL_ERROR	500	An unexpected error occurred on the Databricks side.
TEMPORARILY_UNAVAILABLE	503	The service is temporarily unavailable; the condition is usually transient.
DEADLINE_EXCEEDED	504	The request did not complete before its deadline.

Retries

The official Databricks clients (the CLI, the SDKs, and the Terraform provider) retry transient failures automatically. This guidance is for callers implementing their own client directly against the REST API.

Retry only transient failures. A 503 response (TEMPORARILY_UNAVAILABLE) signals a transient condition that usually clears on its own; retry it with exponential backoff, and when the response carries a RetryInfo detail, wait at least its retry_delay before the next attempt.

Do not automatically retry the other codes:

• RESOURCE_EXHAUSTED (429) often means a quota is exhausted, which can take hours to recover and may carry billing implications. Retry only if you know it reflects short-term throttling, and then with backoff.
• DEADLINE_EXCEEDED (504) means the request did not complete in time. The operation may already have completed on the server, so do not assume it failed; surface the error rather than blindly retrying.
• INTERNAL_ERROR (500) is a server-side fault. Capture the request_id and contact support rather than retrying.
• ABORTED (409) is a concurrency conflict. Retry the whole operation at the application level, not the individual request.
• The remaining 4xx codes (for example INVALID_PARAMETER_VALUE, NOT_FOUND, ALREADY_EXISTS, PERMISSION_DENIED, UNAUTHENTICATED) reflect the request or the current state of the resource; retrying it unchanged fails the same way.

Errors from infrastructure in front of the API (a gateway, proxy, or rate limiter) are not Databricks error objects and carry no error_code; handle these by their HTTP status. A 429 or 503 of this kind is usually transient throttling or unavailability at the edge, so back off and retry, even though the same status returned by the API may not be retryable.

Even for a retryable failure, retry only when the operation is safe to repeat. Reads are always safe; a non-idempotent write, such as a resource creation, can apply twice. Retry a transactional operation as a whole from the start, rather than its individual requests.

Error details

When present, details carries machine-readable context as an array of typed objects, following the gRPC "rich error" model. Each object's @type field identifies its schema as a protobuf type URL; since these are the standard google.rpc detail types, that URL begins with type.googleapis.com/google.rpc.. Unknown detail types can be ignored safely.

The types you are most likely to encounter:

RequestInfo

Carries identifiers for correlating the request with Databricks logs. Include the request_id when contacting support about a failed request.

Field	Type	Description
request_id	string	An opaque identifier for the request, used to locate it in Databricks logs.
serving_data	string	Opaque data captured while serving the request, for Databricks to use when debugging.

ErrorInfo

Identifies the proximate cause of the error in a stable, machine-readable way.

Field	Type	Description
reason	string	A constant identifying the proximate cause (for example, RESOURCE_PROTECTED).
domain	string	The logical grouping the reason belongs to (for example, databricks.com).
metadata	object	Additional structured key/value context about the error.

RetryInfo

Indicates that the request can be retried after a delay. Clients should still apply exponential backoff.

Field	Type	Description
retry_delay	string	The minimum time to wait before retrying, as a duration string ending in s (for example, "3.5s").

BadRequest

Describes which request fields were invalid.

Field	Type	Description
field_violations	array	One entry per invalid field.
field_violations[].field	string	A path to the offending field in the request body.
field_violations[].description	string	Why the field is invalid.

{
  "error_code": "INVALID_PARAMETER_VALUE",
  "message": "Invalid request.",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "field_violations": [
        {
          "field": "name",
          "description": "must not be empty"
        }
      ]
    }
  ]
}