Skip to content
Registry StackDocsDevelopment (unreleased)

Explain one start's refusal

GET
/v1/availability/explain
curl --request GET \
  --url 'https://scheduling.example.test/v1/availability/explain?offering=example&start=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

The separately authorized explanation of one start: the problem code every caller may see, the detailed code only this path discloses, and the refusal in words. A start that admits as things stand answers with no codes at all. The probe is a minimal party, so the answer explains the calendar and the capacity, never another caller’s booking. resource.unavailable is disclosed here and never on the public path, whose answer is capacity.exhausted.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
traceparent
string

Optional W3C trace context continued in the response.

Query Parameters

Section titled “Query Parameters”
offering
required
string
>= 1 characters

Required offering identifier. An offering the deployed policy does not publish is request.not-found.

start
required
string format: date-time

The start to explain.

Responses

Section titled “ Responses ”

200

Section titled “200”

Success

Media typeapplication/json
object
detailedCode
string
explanation
string
offering
required
string
publicCode
string
start
required
string format: date-time
key
additional properties
any
Examplegenerated
{
  "detailedCode": "example",
  "explanation": "example",
  "offering": "example",
  "publicCode": "example",
  "start": "2026-04-15T12:00:00Z"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

400

Section titled “400”

Problem response: request.invalid

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: request.invalid
detail
required
Allowed value: The request could not be read as a Scheduling request.
status
required
Allowed value: 400
title
required
Allowed value: Request invalid
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/request/invalid
Example
{
  "code": "request.invalid",
  "detail": "The request could not be read as a Scheduling request.",
  "status": 400,
  "title": "Request invalid",
  "type": "https://id.registrystack.org/problems/registry-scheduling/request/invalid"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

401

Section titled “401”

Problem response: authentication.refused

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: authentication.refused
detail
required
Allowed value: The bearer credential is missing, invalid, or expired. Sign in again.
status
required
Allowed value: 401
title
required
Allowed value: Authentication refused
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/authentication/refused
Example
{
  "code": "authentication.refused",
  "detail": "The bearer credential is missing, invalid, or expired. Sign in again.",
  "status": 401,
  "title": "Authentication refused",
  "type": "https://id.registrystack.org/problems/registry-scheduling/authentication/refused"
}

Headers

Section titled “Headers”
WWW-Authenticate
Allowed value: Bearer

Bearer authentication challenge.

cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

403

Section titled “403”

Problem response: profile.not-authorized

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: profile.not-authorized
detail
required
Allowed value: The selected Scheduling profile does not authorize this request.
status
required
Allowed value: 403
title
required
Allowed value: Profile not authorized
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/profile/not-authorized
Example
{
  "code": "profile.not-authorized",
  "detail": "The selected Scheduling profile does not authorize this request.",
  "status": 403,
  "title": "Profile not authorized",
  "type": "https://id.registrystack.org/problems/registry-scheduling/profile/not-authorized"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

404

Section titled “404”

Problem response: request.not-found

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: request.not-found
detail
required
Allowed value: The requested route does not exist.
status
required
Allowed value: 404
title
required
Allowed value: Route not found
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/request/not-found
Example
{
  "code": "request.not-found",
  "detail": "The requested route does not exist.",
  "status": 404,
  "title": "Route not found",
  "type": "https://id.registrystack.org/problems/registry-scheduling/request/not-found"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

405

Section titled “405”

Problem response: request.method-not-allowed

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: request.method-not-allowed
detail
required
Allowed value: The route exists but not for this method.
status
required
Allowed value: 405
title
required
Allowed value: Method not allowed
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/request/method-not-allowed
Example
{
  "code": "request.method-not-allowed",
  "detail": "The route exists but not for this method.",
  "status": 405,
  "title": "Method not allowed",
  "type": "https://id.registrystack.org/problems/registry-scheduling/request/method-not-allowed"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

413

Section titled “413”

Problem response: request.body-too-large

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: request.body-too-large
detail
required
Allowed value: The request body exceeds the accepted size.
status
required
Allowed value: 413
title
required
Allowed value: Payload too large
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/request/body-too-large
Example
{
  "code": "request.body-too-large",
  "detail": "The request body exceeds the accepted size.",
  "status": 413,
  "title": "Payload too large",
  "type": "https://id.registrystack.org/problems/registry-scheduling/request/body-too-large"
}

Headers

Section titled “Headers”
cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.

503

Section titled “503”

Problem response: service.unavailable

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused booking.duplicate-active cancellation.cutoff-passed capability.unmatched capacity.exhausted cursor.expired cursor.invalid eligibility.unavailable hold.expired hold.released hook.unavailable horizon.outside idempotency.expired idempotency.key-reused location.closed operation.not-authorized party.capacity-inadequate policy.changed precondition.failed precondition.required prerequisite.missing profile.not-authorized request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type resource.unavailable revision.mismatch schedule.unpublished service.unavailable
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string format: uri
code
required
Allowed value: service.unavailable
detail
required
Allowed value: Scheduling storage is unavailable. Try again after the service recovers.
status
required
Allowed value: 503
title
required
Allowed value: Scheduling service unavailable
type
required
Allowed value: https://id.registrystack.org/problems/registry-scheduling/service/unavailable
Example
{
  "code": "service.unavailable",
  "detail": "Scheduling storage is unavailable. Try again after the service recovers.",
  "status": 503,
  "title": "Scheduling service unavailable",
  "type": "https://id.registrystack.org/problems/registry-scheduling/service/unavailable"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds before retrying the unavailable dependency; the runtime answers 5.

cache-control
Allowed value: no-store

Every answer is marked no-store, so a booking view is never served from a cache.

traceparent
string

W3C trace context for the request and response.