Errors and status codes

InBlack APIs use standard HTTP status semantics, but there is no single response envelope or exhaustive error-code catalog shared by every handler. Read the contract for the route you call and preserve unknown response fields.

Common response shapes

Billing middleware returns JSON such as:

{
  "error": "pillar_not_available",
  "pillar": "studio",
  "tier": "growth",
  "message": "Upgrade your plan to access this feature."
}

Other REST handlers may return only { "error": "message" }, or an error plus a stable code. GraphQL errors use the standard errors[] response and may put machine data in extensions. Do not assume REST and GraphQL share identical code names.

Shared billing and authorization errors

These codes are established by the shared billing middleware and Portal authorization decision service:

HTTP	Code	Meaning
403	subscription_required	No active or trialing subscription
403	no_entitlements	Entitlements were not available to the pillar gate
403	pillar_not_available	The current tier does not include the requested product
402	payment_required	A past-due subscription reached the locked stage
402	account_locked	Access level is locked
402	read_only_access	A write was attempted during the read-only stage

An authorization decision can also return access_denied when role/API-key permission checks fail and usage-specific quota codes such as seat_limit_exceeded or quota_exceeded where that route provides usage metadata.

General status handling

Status	Client action
400	Correct the request body, path value, or business state
401	Refresh or replace the credential
402	Resolve billing state; retries do not bypass the gate
403	Request the required role, entitlement, scope, or tier
404	Recheck the tenant-scoped identifier; do not infer cross-tenant existence
409	Re-read state or correct an idempotency conflict before retrying
422	Correct a semantically invalid payload
429	Honor Retry-After when present and back off
500/502/503/504	Retry only idempotent work, with bounded exponential backoff

Correlation IDs

Clients may send X-AI-Correlation-ID. CorrelationResolver stores it in request context so participating writes and AuditCore events can retain one workflow identifier. The middleware does not guarantee that every HTTP response echoes a correlation_id field.

Generate a stable correlation ID for a multi-call workflow and retain it in your own logs. Never place credentials or personal data in the header.

For MCP-specific machine codes, use Tool errors. For route-specific supported surfaces, use the HTTP route reference.