ENTITY developer reference
ICProblem
Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.
This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.
This is the public candidate schema reading view. Read it with the operation that uses it; a representable field does not establish enabled coverage or entitlement.
RFC9457 bounded safe projection. No company/source/tenant existence leaks. Unknown completion retains original operation and reservation; retries cannot create a new effect. usage_state is a financial-effect projection: an unresolved commitment is uncertain; reconciling remains an order/workflow state. Error status never establishes zero original cost or credit. Access denial discloses no original-operation existence. restart_listing removes the expired cursor and re-reads the same owned resource without creating work. Delivery overflow reports actual financial state: not_started/unchanged before new work, released only after confirmed release, uncertain with the owned original operation when commitment cannot be proved. No new debit may be settled for an undeliverable billed result. Access denials remain opaque. For zero-unit quote creation or adjustment-request intake, an uncertain acknowledgement with no recovered original identifier uses operation_timeout/504/retry_same_request/unchanged and null operation_id/status_path. Retain the exact original idempotency key and canonical payload and reconcile through the existing original-key lookup; do not fabricate reserved units or create a fresh key. completion_uncertain requires its existing proved operation/locator/financial-state predicates and is not this pre-identity fallback. A classification-order status_path must equal /v1/classification-orders/{owned order_id} for the original owned operation; the generic ^/v1/ syntax is not sufficient authority. Never substitute a generic operation route or another order.
Declared type: "object"
Declared fields
This list shows only properties declared directly in this schema. Required labels refer only to this schema’s own required array. Referenced, composed and conditional rules can add constraints; a field not listed as required here is not guaranteed to be optional.
type
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uri"
Reading definition for type
{
"type": "string",
"format": "uri",
"x-profile-maxLength": "string_characters_max"
}title
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for title
{
"type": "string",
"minLength": 1,
"maxLength": 180,
"x-profile-maxLength": "string_characters_max"
}status
Listed in this schema’s required array.
- Declared type
"integer"
Reading definition for status
{
"type": "integer",
"minimum": 400,
"maximum": 599
}code
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for code
{
"type": "string",
"enum": [
"invalid_request",
"unauthenticated",
"permission_denied",
"resource_not_found",
"quote_expired",
"quote_stale",
"idempotency_conflict",
"active_order_conflict",
"budget_exhausted",
"funding_window_too_short",
"rights_unavailable",
"offer_unavailable",
"stale_revision",
"rate_limited",
"operation_reconciling",
"resource_expired",
"dependency_unavailable",
"internal_error",
"operation_timeout",
"completion_uncertain",
"concurrency_limited",
"authority_revoked",
"entitlement_denied",
"cursor_expired",
"payload_too_large",
"limit_out_of_range"
],
"x-profile-maxLength": "string_characters_max"
}request_id
Listed in this schema’s required array.
- Declared type
"string"- Declared format
"uuid"
Reading definition for request_id
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
}operation_id
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for operation_id
{
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}usage_state
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for usage_state
{
"type": "string",
"enum": [
"not_started",
"unchanged",
"reserved",
"settled",
"released",
"uncertain"
],
"x-profile-maxLength": "string_characters_max"
}retry_action
Listed in this schema’s required array.
- Declared type
"string"
Reading definition for retry_action
{
"type": "string",
"enum": [
"do_not_retry",
"refresh_quote",
"poll_original",
"account_recovery",
"retry_same_request",
"reauthenticate",
"restart_listing"
],
"x-profile-maxLength": "string_characters_max"
}status_path
Listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for status_path
{
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}admission_reason
Not listed in this schema’s required array.
- Declared type
"string"
Reading definition for admission_reason
{
"type": "string",
"enum": [
"refresh_interval",
"serving_limit",
"internal_work_limit",
"offer_eligibility",
"freshness_unavailable"
],
"x-profile-maxLength": "string_characters_max"
}next_eligible_at
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for next_eligible_at
{
"anyOf": [
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
}delivery_limit
Not listed in this schema’s required array.
- Declared type
- Not declared directly; consult the complete field definition.
Reading definition for delivery_limit
{
"$ref": "#/components/schemas/DeliveryLimitGuidance"
}detail
Not listed in this schema’s required array.
- Declared type
"string"
Reading definition for detail
{
"type": "string",
"maxLength": 1200
}invalid_fields
Not listed in this schema’s required array.
- Declared type
"array"
Reading definition for invalid_fields
{
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
"reason": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
}
},
"required": [
"path",
"reason"
],
"additionalProperties": false
},
"maxItems": 32,
"x-profile-maxItems": "collection_items_max"
}Schema reading view
Read all retained constraints, including any allOf, oneOf, anyOf, conditional and additional-property constraints. The field list does not combine branches. Explicitly marked private-only omissions mean this view is not an executable substitute for the original schema or a released contract.
{
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "uri",
"x-profile-maxLength": "string_characters_max"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 180,
"x-profile-maxLength": "string_characters_max"
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"enum": [
"invalid_request",
"unauthenticated",
"permission_denied",
"resource_not_found",
"quote_expired",
"quote_stale",
"idempotency_conflict",
"active_order_conflict",
"budget_exhausted",
"funding_window_too_short",
"rights_unavailable",
"offer_unavailable",
"stale_revision",
"rate_limited",
"operation_reconciling",
"resource_expired",
"dependency_unavailable",
"internal_error",
"operation_timeout",
"completion_uncertain",
"concurrency_limited",
"authority_revoked",
"entitlement_denied",
"cursor_expired",
"payload_too_large",
"limit_out_of_range"
],
"x-profile-maxLength": "string_characters_max"
},
"request_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"operation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"usage_state": {
"type": "string",
"enum": [
"not_started",
"unchanged",
"reserved",
"settled",
"released",
"uncertain"
],
"x-profile-maxLength": "string_characters_max"
},
"retry_action": {
"type": "string",
"enum": [
"do_not_retry",
"refresh_quote",
"poll_original",
"account_recovery",
"retry_same_request",
"reauthenticate",
"restart_listing"
],
"x-profile-maxLength": "string_characters_max"
},
"status_path": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"admission_reason": {
"type": "string",
"enum": [
"refresh_interval",
"serving_limit",
"internal_work_limit",
"offer_eligibility",
"freshness_unavailable"
],
"x-profile-maxLength": "string_characters_max"
},
"next_eligible_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"x-profile-maxLength": "string_characters_max"
},
{
"type": "null"
}
]
},
"delivery_limit": {
"$ref": "#/components/schemas/DeliveryLimitGuidance"
},
"detail": {
"type": "string",
"maxLength": 1200
},
"invalid_fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
},
"reason": {
"type": "string",
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
}
},
"required": [
"path",
"reason"
],
"additionalProperties": false
},
"maxItems": 32,
"x-profile-maxItems": "collection_items_max"
}
},
"required": [
"type",
"title",
"status",
"code",
"request_id",
"operation_id",
"usage_state",
"retry_action",
"status_path"
],
"additionalProperties": false,
"description": "RFC9457 bounded safe projection. No company/source/tenant existence leaks. Unknown completion retains original operation and reservation; retries cannot create a new effect. usage_state is a financial-effect projection: an unresolved commitment is uncertain; reconciling remains an order/workflow state. Error status never establishes zero original cost or credit. Access denial discloses no original-operation existence. restart_listing removes the expired cursor and re-reads the same owned resource without creating work. Delivery overflow reports actual financial state: not_started/unchanged before new work, released only after confirmed release, uncertain with the owned original operation when commitment cannot be proved. No new debit may be settled for an undeliverable billed result. Access denials remain opaque. For zero-unit quote creation or adjustment-request intake, an uncertain acknowledgement with no recovered original identifier uses operation_timeout/504/retry_same_request/unchanged and null operation_id/status_path. Retain the exact original idempotency key and canonical payload and reconcile through the existing original-key lookup; do not fabricate reserved units or create a fresh key. completion_uncertain requires its existing proved operation/locator/financial-state predicates and is not this pre-identity fallback. A classification-order status_path must equal /v1/classification-orders/{owned order_id} for the original owned operation; the generic ^/v1/ syntax is not sufficient authority. Never substitute a generic operation route or another order.",
"allOf": [
{
"if": {
"properties": {
"code": {
"const": "invalid_request"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 400
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "unauthenticated"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 401
},
"retry_action": {
"const": "reauthenticate"
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "permission_denied"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "resource_not_found"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 404
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "quote_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
},
"retry_action": {
"enum": [
"refresh_quote"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "quote_stale"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"refresh_quote"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "idempotency_conflict"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "active_order_conflict"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"poll_original"
]
},
"usage_state": {
"enum": [
"reserved",
"uncertain",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "budget_exhausted"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
},
"retry_action": {
"enum": [
"account_recovery"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "funding_window_too_short"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"account_recovery"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "rights_unavailable"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "offer_unavailable"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"refresh_quote"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "stale_revision"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 412
},
"retry_action": {
"enum": [
"poll_original",
"refresh_quote"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "rate_limited"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
},
"retry_action": {
"enum": [
"retry_same_request"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_reconciling"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 409
},
"retry_action": {
"enum": [
"poll_original"
]
},
"usage_state": {
"enum": [
"reserved",
"uncertain",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "resource_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "dependency_unavailable"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 503
},
"retry_action": {
"enum": [
"retry_same_request",
"poll_original"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged",
"reserved",
"uncertain"
]
}
}
}
},
{
"if": {
"properties": {
"retry_action": {
"const": "poll_original"
}
},
"required": [
"retry_action"
]
},
"then": {
"properties": {
"status_path": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"required": [
"admission_reason"
]
},
"then": {
"required": [
"next_eligible_at"
],
"properties": {
"usage_state": {
"type": "string",
"enum": [
"not_started",
"unchanged"
],
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "internal_error"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 500
},
"retry_action": {
"enum": [
"retry_same_request",
"poll_original"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged",
"reserved",
"settled",
"released",
"uncertain"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "operation_timeout"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 504
},
"retry_action": {
"enum": [
"retry_same_request",
"poll_original"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged",
"reserved",
"settled",
"released",
"uncertain"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "completion_uncertain"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 503
},
"retry_action": {
"enum": [
"poll_original"
]
},
"usage_state": {
"enum": [
"reserved",
"uncertain"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "concurrency_limited"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 429
},
"retry_action": {
"enum": [
"retry_same_request"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "authority_revoked"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "entitlement_denied"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 403
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "cursor_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 410
},
"retry_action": {
"enum": [
"restart_listing"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "payload_too_large"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 413
},
"retry_action": {
"enum": [
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"status": {
"const": 422
},
"retry_action": {
"enum": [
"refresh_quote",
"poll_original",
"do_not_retry"
]
},
"usage_state": {
"enum": [
"not_started",
"unchanged",
"released",
"uncertain"
]
}
}
}
},
{
"if": {
"properties": {
"retry_action": {
"const": "poll_original"
}
},
"required": [
"retry_action"
]
},
"then": {
"properties": {
"operation_id": {
"type": "string",
"format": "uuid",
"x-profile-maxLength": "string_characters_max"
},
"status_path": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"pattern": "^/v1/",
"x-profile-maxLength": "string_characters_max"
}
}
}
},
{
"if": {
"properties": {
"usage_state": {
"const": "uncertain"
}
},
"required": [
"usage_state"
]
},
"then": {
"properties": {
"retry_action": {
"const": "poll_original"
}
}
}
},
{
"if": {
"properties": {
"code": {
"enum": [
"unauthenticated",
"permission_denied",
"authority_revoked",
"entitlement_denied",
"resource_not_found"
]
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
}
}
}
},
{
"if": {
"properties": {
"admission_reason": {
"enum": [
"serving_limit",
"refresh_interval"
]
}
},
"required": [
"admission_reason"
]
},
"then": {
"properties": {
"status": {
"const": 429
},
"code": {
"const": "rate_limited"
},
"usage_state": {
"enum": [
"not_started",
"unchanged"
]
},
"retry_action": {
"const": "retry_same_request"
}
},
"required": [
"next_eligible_at"
]
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
}
},
"required": [
"code"
]
},
"then": {
"required": [
"delivery_limit"
]
}
},
{
"if": {
"properties": {
"code": {
"const": "limit_out_of_range"
},
"delivery_limit": {
"properties": {
"phase": {
"const": "input"
}
},
"required": [
"phase"
]
}
},
"required": [
"code",
"delivery_limit"
]
},
"then": {
"properties": {
"usage_state": {
"const": "not_started"
}
}
}
},
{
"if": {
"properties": {
"code": {
"const": "resource_expired"
}
},
"required": [
"code"
]
},
"then": {
"properties": {
"operation_id": {
"type": "null"
},
"status_path": {
"type": "null"
}
}
}
}
]
}