Error Handling

The Skycloak API uses standard HTTP status codes and returns structured error information following RFC 9457 (Problem Details for HTTP APIs).

HTTP Status Codes

Error Response Format

All errors follow RFC 9457 and are returned with Content-Type: application/problem+json.

{
  "type": "https://skycloak.io/docs/api/errors#bad-request",
  "title": "Bad Request",
  "detail": "Human-readable explanation of this specific occurrence",
  "status": 400,
  "instance": "/logs/requests/d24b2953-ce05-488e-bf31-67de50d3d085"
}

Validation errors include an additional errors array — see #validation-failed.

Problem Detail Types

bad-request

Type URI: https://skycloak.io/docs/api/errors#bad-request HTTP Status: 400

The request was syntactically valid but could not be processed due to a domain-level constraint (e.g., referencing a resource that is in an invalid state for this operation).

{
  "type": "https://skycloak.io/docs/api/errors#bad-request",
  "title": "Bad Request",
  "detail": "Cluster must be in 'available' state to create a realm",
  "status": 400
}

unauthorized

Type URI: https://skycloak.io/docs/api/errors#unauthorized HTTP Status: 401

Authentication credentials are missing or invalid. Include a valid API key in the API-Key header.

{
  "type": "https://skycloak.io/docs/api/errors#unauthorized",
  "title": "Unauthorized",
  "detail": "Missing or invalid authentication",
  "status": 401
}

plan-limit-exceeded

Type URI: https://skycloak.io/docs/api/errors#plan-limit-exceeded HTTP Status: 402

The requested action is not allowed on your current subscription plan. Upgrade your plan to proceed.

{
  "type": "https://skycloak.io/docs/api/errors#plan-limit-exceeded",
  "title": "Plan Limit Exceeded",
  "detail": "Your current plan allows a maximum of 2 clusters",
  "status": 402,
  "current_plan": "starter",
  "required_plan": "pro",
  "current_usage": 2,
  "current_limit": 2
}

forbidden

Type URI: https://skycloak.io/docs/api/errors#forbidden HTTP Status: 403

Authentication succeeded but the API key does not have the required scope for this operation. See Authentication & Scopes for the full list of available scopes.

{
  "type": "https://skycloak.io/docs/api/errors#forbidden",
  "title": "Forbidden",
  "detail": "API key does not have the required scope: clusters:write",
  "status": 403
}

not-found

Type URI: https://skycloak.io/docs/api/errors#not-found HTTP Status: 404

The requested resource does not exist or is not accessible to your workspace.

{
  "type": "https://skycloak.io/docs/api/errors#not-found",
  "title": "Not Found",
  "detail": "Cluster 'd290f1ee-6c54-4b01-90e6-d701748f0851' not found",
  "status": 404
}

conflict

Type URI: https://skycloak.io/docs/api/errors#conflict HTTP Status: 409

The request conflicts with the current state of the resource, such as a duplicate name or a delete blocked by an existing assignment.

{
  "type": "https://skycloak.io/docs/api/errors#conflict",
  "title": "Conflict",
  "detail": "A cluster named 'production' already exists in this workspace",
  "status": 409
}

validation-failed

Type URI: https://skycloak.io/docs/api/errors#validation-failed HTTP Status: 422

One or more request fields failed validation. The errors array contains a per-field breakdown.

{
  "type": "https://skycloak.io/docs/api/errors#validation-failed",
  "title": "Validation Failed",
  "detail": "Validation failed",
  "status": 422,
  "errors": [
    {
      "field": "/name",
      "detail": "Name must be between 1 and 63 characters",
      "code": "minimum",
      "value": "ab"
    },
    {
      "field": "/size",
      "detail": "Must be one of: small, medium, large",
      "code": "invalid_enum",
      "value": "xlarge"
    }
  ]
}

Each entry in errors:

rate-limit-exceeded

Type URI: https://skycloak.io/docs/api/errors#rate-limit-exceeded HTTP Status: 429

The client has sent too many requests. Check the Retry-After response header for how many seconds to wait before retrying.

{
  "type": "https://skycloak.io/docs/api/errors#rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "detail": "Rate limit exceeded. Retry after 1 second.",
  "status": 429
}

See Rate Limiting for the full set of headers included on every response.

internal-error

Type URI: https://skycloak.io/docs/api/errors#internal-error HTTP Status: 500

An unexpected server-side error occurred. If the problem persists, contact support with the request details.

{
  "type": "https://skycloak.io/docs/api/errors#internal-error",
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred",
  "status": 500
}

Retry Strategies

When to Retry

Always retry (with backoff):

• 429 Too Many Requests — respect the Retry-After header
• 500 Internal Server Error
• 503 Service Unavailable
• Network errors/timeouts

Never retry:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 409 Conflict
• 422 Unprocessable Entity

Exponential Backoff

For transient errors (5xx, 429), use exponential backoff with jitter to avoid thundering-herd problems. Start with a short delay (e.g., 1s), double on each retry, and cap at a maximum (e.g., 32s).