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

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
202	Accepted	Async operation started
204	No Content	Success, no body returned
400	Bad Request	Invalid request format, parameters, or headers
401	Unauthorized	Missing or invalid authentication
402	Payment Required	Action not allowed on your current plan
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn’t exist
409	Conflict	Resource conflict (e.g., duplicate name)
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	Service temporarily unavailable

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"
}

Field	Type	Description
type	string	URI identifying the problem type. Points to the relevant section in this document.
title	string	Short, stable summary of the problem type.
detail	string	Human-readable explanation specific to this occurrence.
status	integer	HTTP status code.
instance	string (optional)	URI identifying this specific occurrence (e.g., a log entry).

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
}

Extension Field	Type	Description
current_plan	string	Your active subscription plan.
required_plan	string	The minimum plan that allows this action.
current_usage	integer	Your current usage of the limited resource.
current_limit	integer	The limit imposed by your current plan.

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:

Field	Type	Description
field	string	JSON Pointer (RFC 6901) to the invalid field (e.g., /name, /replicas). Empty string for body-level errors.
detail	string	Human-readable description of the failure.
code	string (optional)	Machine-readable validation code (e.g., required, minimum, invalid_enum, pattern). minimum and maximum also cover string and array length limits.
value	any (optional)	The rejected value for safe scalar inputs. Omitted for sensitive fields, uploaded files, binary-looking strings, and complex request objects.

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).