Skip to main content

Integration API error code catalog

Every stable public error code this platform can return, generated from the backend's own error registry. Every failure response uses the same envelope: { type, title, status, code, detail?, traceId? }. code is always one of the values below; a client should treat any OTHER string as an unknown future code (forward-compatible) rather than an error in itself.

An entry marked Reserved has a permanent slot in this catalog but is not emitted by any current Phase 6 operation — it is safe to handle in a switch/branch today so a client is already correct once a later release starts emitting it.

An entry marked Console only is registered so the platform can render its title, but no operation of the Integration API lists it in its error responses. Nothing in the endpoint reference promises it to a client that uses an integration API key, so do not build a branch on it from this catalog alone.

CodeHTTP statusAvailability
ACTIVATION_EVIDENCE_STALE409Console only
ACTIVATION_REQUEST_STALE409Console only
AI_SPEND_CAP_EXCEEDED402Reserved
AUTHENTICATION_REQUIRED401Active
CONFLICT409Console only
DATASET_CURSOR_INVALID400Active
DATASET_DELTA_SCHEMA_MISMATCH409Active
DATASET_FILTER_INVALID400Active
DATASET_NOT_DECLARED409Active
DATASET_QUERY_TIMEOUT504Active
DATASET_SCHEMA_CHANGED409Active
DATASET_VERSION_REMOVED404Active
DELIVERY_NOT_EXHAUSTED409Console only
DELIVERY_RETRY_FORBIDDEN403Console only
DOCUMENT_BASE64_INVALID400Active
DOCUMENT_BYTES_TOO_LARGE400Active
DOCUMENT_COUNT_EXCEEDED400Active
DOCUMENT_FILE_MISSING400Active
DOCUMENT_MEDIA_TYPE_MISMATCH400Active
DOCUMENT_MEDIA_TYPE_UNSUPPORTED400Active
DOCUMENT_TOTAL_BYTES_EXCEEDED400Active
DOCUMENT_UNEXPECTED_FIELD400Active
EXTRACT_SAMPLE_STEP_NOT_FOUND422Console only
FORBIDDEN403Active
INTERNAL_ERROR500Active
NOT_FOUND404Active
REQUEST_BODY_TOO_LARGE413Active
RULESET_CURSOR_INVALID400Active
RUN_CURSOR_INVALID400Active
TEMPLATE_COPY_CONFLICT409Console only
TEMPLATE_METADATA_INVALID400Console only
TEMPLATE_VERSION_UNAVAILABLE404Console only
TRANSLATION_UPSTREAM_FAILED502Console only
VALIDATION_FAILED400Active
WEBHOOK_DESTINATION_URL_REJECTED400Console only

ACTIVATION_EVIDENCE_STALE​

HTTP status: 409

Availability: Console only — no operation of the Integration API lists this code in its error responses

Rebuild the activation evidence against the current active version.

ACTIVATION_REQUEST_STALE​

HTTP status: 409

Availability: Console only — no operation of the Integration API lists this code in its error responses

The activation request no longer matches the working revision.

AI_SPEND_CAP_EXCEEDED​

HTTP status: 402

Availability: Reserved — not yet emitted by any Phase 6 operation

The tenant AI spend cap has been reached.

AUTHENTICATION_REQUIRED​

HTTP status: 401

Availability: Active

Authentication is required for this request.

CONFLICT​

HTTP status: 409

Availability: Console only — no operation of the Integration API lists this code in its error responses

The request conflicts with the current state of the resource.

DATASET_CURSOR_INVALID​

HTTP status: 400

Availability: Active

The presented dataset cursor is invalid or has expired.

DATASET_DELTA_SCHEMA_MISMATCH​

HTTP status: 409

Availability: Active

A partial update cannot follow a change of the dataset declaration; push a full snapshot instead.

DATASET_FILTER_INVALID​

HTTP status: 400

Availability: Active

A dataset row filter is malformed, or names a field that cannot be filtered on.

DATASET_NOT_DECLARED​

HTTP status: 409

Availability: Active

The ruleset does not declare this dataset any more, so no data can be pushed to it.

DATASET_QUERY_TIMEOUT​

HTTP status: 504

Availability: Active

The dataset row query exceeded its time limit. Narrow the filters and retry.

DATASET_SCHEMA_CHANGED​

HTTP status: 409

Availability: Active

The dataset declaration is not the one the push was prepared for; read the current declaration and push again.

DATASET_VERSION_REMOVED​

HTTP status: 404

Availability: Active

The rows of this dataset version were removed by the retention policy.

DELIVERY_NOT_EXHAUSTED​

HTTP status: 409

Availability: Console only — no operation of the Integration API lists this code in its error responses

This delivery has not exhausted its automatic attempts and cannot be manually retried.

DELIVERY_RETRY_FORBIDDEN​

HTTP status: 403

Availability: Console only — no operation of the Integration API lists this code in its error responses

Manually retrying a webhook delivery requires an editor or approver tenant delivery role.

DOCUMENT_BASE64_INVALID​

HTTP status: 400

Availability: Active

A submitted document is not valid canonical base64.

DOCUMENT_BYTES_TOO_LARGE​

HTTP status: 400

Availability: Active

A submitted document exceeds the per-document byte ceiling.

DOCUMENT_COUNT_EXCEEDED​

HTTP status: 400

Availability: Active

The request names more documents than the platform maximum.

DOCUMENT_FILE_MISSING​

HTTP status: 400

Availability: Active

No file was presented in the upload request.

DOCUMENT_MEDIA_TYPE_MISMATCH​

HTTP status: 400

Availability: Active

A submitted document's declared media type does not match its content.

DOCUMENT_MEDIA_TYPE_UNSUPPORTED​

HTTP status: 400

Availability: Active

A submitted document declares a media type the platform does not accept.

DOCUMENT_TOTAL_BYTES_EXCEEDED​

HTTP status: 400

Availability: Active

The submitted documents exceed the aggregate byte ceiling.

DOCUMENT_UNEXPECTED_FIELD​

HTTP status: 400

Availability: Active

The upload request carried an unexpected form field.

EXTRACT_SAMPLE_STEP_NOT_FOUND​

HTTP status: 422

Availability: Console only — no operation of the Integration API lists this code in its error responses

The requested step is not an extract step of the saved draft revision.

FORBIDDEN​

HTTP status: 403

Availability: Active

The caller is not permitted to perform this operation.

INTERNAL_ERROR​

HTTP status: 500

Availability: Active

An unexpected error occurred while processing the request.

NOT_FOUND​

HTTP status: 404

Availability: Active

The requested resource does not exist or is not visible to this caller.

REQUEST_BODY_TOO_LARGE​

HTTP status: 413

Availability: Active

The request body exceeds the permitted size for this route.

RULESET_CURSOR_INVALID​

HTTP status: 400

Availability: Active

The presented ruleset-list cursor is invalid or has expired.

RUN_CURSOR_INVALID​

HTTP status: 400

Availability: Active

The presented run-history cursor is invalid or has expired.

TEMPLATE_COPY_CONFLICT​

HTTP status: 409

Availability: Console only — no operation of the Integration API lists this code in its error responses

The template assignment or copy already exists.

TEMPLATE_METADATA_INVALID​

HTTP status: 400

Availability: Console only — no operation of the Integration API lists this code in its error responses

The template metadata or reason is invalid.

TEMPLATE_VERSION_UNAVAILABLE​

HTTP status: 404

Availability: Console only — no operation of the Integration API lists this code in its error responses

The template version does not exist or is unavailable to this caller.

TRANSLATION_UPSTREAM_FAILED​

HTTP status: 502

Availability: Console only — no operation of the Integration API lists this code in its error responses

The translation could not be completed. Try again.

VALIDATION_FAILED​

HTTP status: 400

Availability: Active

The request did not satisfy the required schema.

WEBHOOK_DESTINATION_URL_REJECTED​

HTTP status: 400

Availability: Console only — no operation of the Integration API lists this code in its error responses

The destination URL does not satisfy the outbound webhook policy.