Interpret REST API error responses

The automation orchestrator REST API returns error responses in the RFC 9457 (Problem Details for HTTP APIs) format. All error responses use the application/problem+json content type.

Error response structure
Copy link

Each error response contains the following fields:

Expand
Table 1. Error response fields
Field Type Description
type String A URI that identifies the error type. Use this value for programmatic error handling.
title String A short, human-readable summary of the error.
detail String A detailed explanation of the specific error occurrence. Maximum 2,000 characters.
code String A machine-readable error code for the specific error condition.
retryable Boolean Indicates whether retrying the request might succeed.
instance String The request URL that triggered the error. Maximum 2,048 characters.

Example error response
Copy link

{
  "type": "https://api.example.com/errors/resource-not-found",
  "title": "Not Found",
  "detail": "Workflow with ID '550e8400-e29b-41d4-a716-446655440000' does not exist.",
  "code": "RESOURCE_NOT_FOUND",
  "retryable": false,
  "instance": "/api/v1/workflows/550e8400-e29b-41d4-a716-446655440000"
}

Error types
Copy link

The following table lists the error types that the REST API can return:

Expand
Table 2. REST API error types
Error type URI HTTP status Description
https://api.example.com/errors/unauthorized 401 The request lacks valid authentication credentials.
https://api.example.com/errors/token-expired 401 The access token has expired. Refresh the token and retry.
https://api.example.com/errors/forbidden 403 The authenticated user does not have permission to perform the requested action.
https://api.example.com/errors/resource-not-found 404 The requested resource does not exist.
https://api.example.com/errors/resource-ownership 403 The authenticated user does not own the requested resource.
https://api.example.com/errors/name-conflict 409 A resource with the same name already exists in the same scope.
https://api.example.com/errors/resource-conflict 409 The request conflicts with the current state of the resource.
https://api.example.com/errors/method-not-allowed 405 The HTTP method is not supported for this endpoint.
https://api.example.com/errors/validation-error 400, 422 The request body or parameters contain invalid or missing fields.
https://api.example.com/errors/integrity-constraint 409 A database uniqueness constraint was violated.
https://api.example.com/errors/resource-not-published 400 The operation requires a published resource version.
https://api.example.com/errors/payload-too-large 413 The request body exceeds the maximum allowed size.
https://api.example.com/errors/provider-error 502 An upstream service or tool provider returned an error.
https://api.example.com/errors/integration-error 502 An external integration returned an error.
https://api.example.com/errors/service-unavailable 503 A required back-end service is temporarily unavailable.
https://api.example.com/errors/publish-validation 400 The workflow version failed publish-time validation.
https://api.example.com/errors/rate-limited 429 The user has exceeded the configured rate limit. Retry after the duration specified in theRetry-After header.
https://api.example.com/errors/internal-error 500 An unexpected error occurred on the server.

HTTP status codes
Copy link

For the complete list of HTTP status codes returned by the REST API, see the format API requests and interpret responses reference topic.

Rate limit error handling
Copy link

When a user exceeds their configured rate limit, the API returns a 429 Too Many Requests response. The response includes a Retry-After header and RFC 9457 problem details. Rate limiting is configured per user through runtime settings. Service account requests authenticated with bearer tokens are rate-limited by client IP address, not by service account identity.

When an external tool provider returns a rate limit error during workflow execution, the automation orchestrator sets retryable to true. It then applies exponential backoff before retrying.