Errors

Every error response uses the envelope described below. Code against it as the default. CI HUB-originated errors (source: "cihub") return it today. DAM-originated errors (source: "integration") are still being migrated, so some still arrive in an older form or with envelope fields unset. Read the envelope defensively until that work completes. The source field distinguishes errors originating in CI HUB from errors originating in a DAM provider.

Envelope

{
  "error": {
    "status": 403,
    "code": "integration-forbidden",
    "source": "integration",
    "message": "Access denied by the integration",
    "details": "403 Forbidden - insufficient_permissions",
    "provider": "bynder"
  }
}

Field	Always present	Meaning
`status`	yes	HTTP status mirrored in the body
`code`	yes	Machine-readable identifier
`source`	yes	`cihub` or `integration`
`message`	yes	Human-readable summary, safe for end-user display
`details`	no	Structured or string context. Useful for logs, not for end users.
`provider`	only when `source` is `integration`	DAM that produced the error (`bynder`, `aem`, etc.)

The HTTP status in the response line equals error.status.

The presence guarantees above hold for the structured envelope, which every cihub error and every migrated integration error returns. A DAM error still on the legacy path can instead arrive as { "message": "Error", "details": "..." } with no error object, so check that error exists before reading error.code.

The source field

The support chain runs:

End user → Partner platform → CI HUB → DAM provider

source: "cihub": CI HUB rejected the request. Examples: missing token, expired subscription, rate limit. Direct support tickets to CI HUB.
source: "integration": a DAM provider rejected the request. Examples: Bynder permission denied, AEM 404. Direct support to the DAM owner.

Status codes

cihub errors use standard HTTP status conventions. integration errors forward the DAM's HTTP status when the integration classifies it as a known case; otherwise a default status applies.

Backwards compatibility

Top-level fields are preserved for clients that pre-date the structured envelope.

Top-level field	Source	Notes
`errorCode`	mirrors `error.code`	Available for legacy clients that switch on a top-level field.
`message`	constant `'Error'`	Not the human-readable message. The user-facing string is `error.message`.
`details`	`route prefix + error.message`	The route prefix plus the underlying message. Different from `error.details`, which carries structured context.

New integrations should read error.* only.

Code catalog

Switch on error.code; display error.message to end users. The source column tells you who owns the failure.

400 Bad Request

Code	Source	When	Action
`cihub-sdk-email-missing`	cihub	No `email` in the JWT claim or the request body, or the resolved value fails email-format validation.	Include `email` in the JWT payload or send it in the request body. Verify it parses as a valid email.
`cihub-validation-error`	cihub	A required parameter is missing or malformed.	Check the endpoint reference. The `details` field carries the validation message.
`cihub-bad-request`	cihub	An ad-hoc validation rejected the request body or query (route-specific check that did not run through schema validation).	Check the endpoint reference. The `details` field names the issue.
`integration-operation-failed`	integration	A DAM operation was rejected by the provider with a request-level error.	The `details` field carries the upstream message. Surface it to the user or route to the DAM owner.

401 Unauthorized

Code	Source	When	Action
`cihub-sdk-token-missing`	cihub	`Authorization` header absent on the exchange call.	Send `Authorization: Bearer <partner-signed-jwt>`.
`cihub-sdk-token-invalid`	cihub	Partner JWT is malformed; signed with the wrong algorithm; missing required header or claim fields; signature verification failed; `iat` is more than 30s in the future; or `iat` is older than `maxTokenAge` (more than `maxTokenAge` seconds in the past).	Mint a fresh JWT. Verify `alg: RS256`, that `kid` matches a key in the JWKS, and that all required claims are present. Sign a new token per exchange so `iat` stays recent.
`cihub-sdk-token-expired`	cihub	Partner JWT past `exp`.	Mint a new JWT with a fresh `iat` and `exp`.
`cihub-access-token-missing`	cihub	`Authorization` header absent on a post-exchange API call.	Send `Authorization: Bearer <CI HUB access_token>`.
`cihub-access-token-invalid`	cihub	CI HUB access token is present but invalid or expired.	Mint a new access token using the refresh token. If refresh fails, run the token exchange again.
`cihub-refresh-token-invalid`	cihub	On `GET /auth/refreshToken`, the `provider-authorization` token is not a CI HUB refresh token (for example an access token sent in its place), or its `sub` does not match the access token. A signature failure, malformed token, or expired refresh token returns `provider-access-token-invalid` (403) instead.	Send the refresh token returned by exchange in `provider-authorization`. If it has expired, run the token exchange again.
`integration-auth-failed`	integration	The DAM provider rejected the forwarded authentication, for example a token revoked at the DAM or a failed token refresh on the DAM side. `provider` names the integration.	Refresh the DAM token where supported, otherwise restart the DAM login flow.

402 Payment Required

Code	Source	When	Action
`cihub-sdk-no-subscription`	cihub	Partner company has no active SDK subscription, or the assigned product is not enabled for SDK use.	Contact the CI HUB partner manager. Resolution is operational.
`cihub-license-required`	cihub	The user has no active license for the requested product.	Confirm the user is associated with the partner company and the subscription has seats available.

403 Forbidden

Code	Source	When	Action
`cihub-sdk-partner-unknown`	cihub	The `iss` claim is not registered in `sdk.partners`.	Verify the issuer string matches the registered value exactly, including trailing slash.
`cihub-sdk-audience-invalid`	cihub	The `aud` claim does not match the registered audience.	Set `aud` to the registered value (default `https://api.ci-hub.com`).
`cihub-access-denied`	cihub	A whitelist or role check rejected the request.	The `details` field describes the rejected check. The fix is typically operational (account-level configuration).
`provider-access-token-missing`	cihub	A content call requires a DAM connection token (`provider-authorization` header) but none was sent.	Complete the DAM login flow for this provider and send the resulting token in `provider-authorization`.
`provider-access-token-invalid`	cihub	The `provider-authorization` token failed verification, was malformed, or has expired. Covers both a DAM connection token on content calls and a CI HUB refresh token whose signature or expiry failed on `GET /auth/refreshToken`.	For a DAM token, re-run the DAM login flow. For a CI HUB refresh token, run the token exchange again.
`integration-forbidden`	integration	DAM provider rejected the call with a permission error.	Surface the message to the end user. Permission decisions are governed by the DAM.

404 Not Found

Code	Source	When	Action
`cihub-not-found`	cihub	The path does not exist on CI HUB.	Check the endpoint reference for the correct route and casing.
`integration-not-found`	integration	Asset or folder does not exist in the DAM, or the user cannot see it.	Re-query the parent folder. The asset may have been moved or deleted in the DAM.
`integration-not-available`	integration	The asset exists in the DAM but the requested rendition or download form is not available.	Fall back to a different rendition. Check `providerInfo` for supported renditions.

409 Conflict

Code	Source	When	Action
`cihub-conflict`	cihub	An action conflicts with current state (resource already exists, trial already activated, etc.).	The `details` field describes the conflict.

429 Too Many Requests

Code	Source	When	Action
`cihub-rate-limited`	cihub	Per-partner rate limit on the exchange endpoint exceeded (default 60 requests per minute, configurable per partner).	Back off and retry. Honor the standard rate-limit headers.

500 Internal Server Error

Code	Source	When	Action
`cihub-internal-error`	cihub	An explicit 500 emitted by route code.	Retry once. File a ticket with the `details` field and a recent timestamp if it persists.
`cihub-unknown-error`	cihub	An unhandled exception reached the route safety net. The `status` echoes the underlying error's status (or 500 if missing).	Retry once. File a ticket with the timestamp; CI HUB logs carry the stack trace.

501 Not Implemented

Code	Source	When	Action
`integration-not-implemented`	integration	The DAM integration does not implement this operation. The capability is intended but absent today.	Gate the affordance in the host UI based on the provider's capability flags.
`integration-not-supported`	integration	The DAM provider does not support this feature at all.	Permanent. Check `providerInfo` before exposing the affordance.

The details field

details is optional. When present on an integration error, it carries the upstream message verbatim. Use error.message for end-user strings. Reserve error.details for logs and support tickets.

Changelog →

Notable changes to the API and documentation