Error Contract

Status: Contract Frozen (integration CLI endpoints) Date: 2026-02-06

Envelope

All integration CLI endpoints return:

interface ApiError {
  code: string
  message: string
  details?: object
}

Notes:

• New integration endpoints use this shape only.
• Legacy endpoints may continue using existing { error, message } until migrated.

Codes

Auth

• MISSING_API_KEY (400)
• INVALID_API_KEY (401)
• EXPIRED_API_KEY (401)
• REVOKED_API_KEY (401)
• INVALID_TOKEN (401)
• EXPIRED_TOKEN (401)
• RATE_LIMITED (429)

Permissions

• SCOPE_DENIED (403)
• PRINCIPAL_DENIED (403)
• ADAPTER_NOT_ALLOWED (403)

Validation

• MISSING_REQUIRED_COLUMNS (400)
• INVALID_FILE_FORMAT (400)
• INVALID_ADAPTER (400)
• INVALID_EXPIRES_AT (400)
• DUPLICATE_CANONICAL_COLUMN (400)
• FIELD_TOO_LONG (400)

Conflict and System

• DUPLICATE_UPLOAD (409)
• FILE_TOO_LARGE (413)
• UNPROCESSABLE_CONTENT (422)
• NOT_FOUND (404)
• INTERNAL_ERROR (500)

Outcome Mapping (CLI)

• Header/schema validation failures map to preflight_failed.
• Row/content sanitization failures map to sanitization_failed.

This avoids overloading preflight_failed for row-level sanitizer rejects.

Detail Conventions

• PRINCIPAL_DENIED should include principal guard context:
  • details.required: allowed principals
  • details.actual: resolved principal for request
• INVALID_EXPIRES_AT should include validation reason:
  • details.reason: "must be a valid ISO 8601 date" or "must be in the future"