Error Codes

Complete reference of 53 error codes across 10 categories returned by the Integration Hub Service.

Error response formatjson

{
  "statusCode": 400,
  "code": "ERR_INTEGRATION_HUB_SVC_INVALID_INTENT",
  "message": "The provided intent is not valid for the specified category",
  "path": "/integrationhub/v1/execute",
  "timestamp": "2026-02-20T10:30:00.000Z"
}

Execution ErrorsExecution

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_INVALID_INTENT`	400	`INVALID_INTENT`	The provided intent is not valid for the specified category	Verify the intent follows <domain>.<action> pattern (e.g., message.send.sms)
`ERR_INTEGRATION_HUB_SVC_UNAUTHORIZED`	401	`UNAUTHORIZED`	Authentication failed for the execution request	Provide a valid Bearer token in the Authorization header
`ERR_INTEGRATION_HUB_SVC_FORBIDDEN`	403	`FORBIDDEN`	Tenant access denied for execution	Ensure x-tenant-id header matches the tenant in your JWT token
`ERR_INTEGRATION_HUB_SVC_QUOTA_EXCEEDED`	422	`QUOTA_EXCEEDED`	Monthly execution quota has been exceeded	Upgrade subscription tier or wait for quota reset
`ERR_INTEGRATION_HUB_SVC_RATE_LIMIT_EXCEEDED`	429	`RATE_LIMIT_EXCEEDED`	Per-minute rate limit exceeded for executions	Wait for Retry-After duration, implement exponential backoff
`ERR_INTEGRATION_HUB_SVC_ALL_PROVIDERS_FAILED`	503	`ALL_PROVIDERS_FAILED`	All providers in the fallback chain have failed	Check details.errors array for individual provider failures
`ERR_INTEGRATION_HUB_SVC_NO_PROVIDERS`	503	`NO_PROVIDERS`	No providers are available for the requested intent	Install a provider via the marketplace for the requested category
`ERR_INTEGRATION_HUB_SVC_INVALID_REQUEST`	400	`INVALID_REQUEST`	Required execution parameters are missing	Ensure request includes category, intent, and payload fields
`ERR_INTEGRATION_HUB_SVC_EXECUTION_FAILED`	503	`EXECUTION_FAILED`	Generic execution failure after all error handling	Check error message and service logs with x-request-id

Provider ErrorsProvider

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_PROVIDER_NOT_FOUND`	404	`PROVIDER_NOT_FOUND`	The requested provider does not exist	Use GET /providers to list available providers. Keys are case-sensitive.
`ERR_INTEGRATION_HUB_SVC_PROVIDER_CREATE_FAILED`	400	`PROVIDER_CREATE_FAILED`	Provider creation failed due to invalid configuration	Check required fields: provider_key, display_name, category, status
`ERR_INTEGRATION_HUB_SVC_ADAPTER_NOT_FOUND`	404	`ADAPTER_NOT_FOUND`	No adapter implementation exists for the provider	Contact platform team. Check details.availableAdapters list.

Credential ErrorsCredential

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_CREDENTIAL_BIND_FAILED`	400	`CREDENTIAL_BIND_FAILED`	Credential binding (storage) failed	Verify providerId, credential format, and vault-svc availability
`ERR_INTEGRATION_HUB_SVC_INTERNAL_CREDENTIAL_BIND_FAILED`	400	`INTERNAL_CREDENTIAL_BIND_FAILED`	Internal (mTLS) credential binding failed	Same as CREDENTIAL_BIND_FAILED. Also verify mTLS certificates.
`ERR_INTEGRATION_HUB_SVC_CREDENTIAL_NOT_FOUND`	404	`CREDENTIAL_NOT_FOUND`	No active credentials found for the provider	Bind credentials first using POST /credentials/bind
`ERR_INTEGRATION_HUB_SVC_CREDENTIAL_EXPIRED`	400	`CREDENTIAL_EXPIRED`	The stored credentials have expired	Re-bind with fresh credentials or use OAuth refresh token flow

OAuth ErrorsOAuth

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_MISSING_TOKEN`	400	`MISSING_TOKEN`	Access token not provided in the request body	Include { "access_token": "<token>" } in the request body
`ERR_OAUTH_PROVIDER_REQUIRED`	400	`OAUTH_PROVIDER_REQUIRED`	The provider field is missing from the OAuth callback	Include provider in the callback payload (e.g., "provider": "google")
`ERR_OAUTH_CODE_REQUIRED`	400	`OAUTH_CODE_REQUIRED`	The code field is missing from the OAuth callback	Include the authorization code from the OAuth provider
`ERR_OAUTH_TOKEN_EXCHANGE_FAILED`	400	`OAUTH_TOKEN_EXCHANGE_FAILED`	Authorization code exchange for access token failed	Check code expiry (30-60s), code_verifier, redirect URI match
`ERR_OAUTH_UNSUPPORTED_PROVIDER`	400	`OAUTH_UNSUPPORTED_PROVIDER`	The specified OAuth provider is not supported	Use: google, microsoft, linkedin, twitter, apple, facebook, instagram, github
`ERR_OAUTH_REFRESH_NOT_SUPPORTED`	400	`OAUTH_REFRESH_NOT_SUPPORTED`	Provider does not support token refresh	For Apple/Instagram, re-authenticate user for new tokens
`ERR_OAUTH_REFRESH_FAILED`	400	`OAUTH_REFRESH_FAILED`	Token refresh failed at the provider	Re-authenticate through the full OAuth flow
`ERR_OAUTH_REVOCATION_FAILED`	400	`OAUTH_REVOCATION_FAILED`	Token revocation failed at the provider endpoint	Retry. If token already expired, revocation may not be necessary.
`ERR_OAUTH_PROFILE_FETCH_FAILED`	400	`OAUTH_PROFILE_FETCH_FAILED`	Profile fetch from provider API failed	Refresh access token and retry. Verify required scopes.
`ERR_TOTP_INVALID`	400	`TOTP_INVALID`	The TOTP code is invalid	Ensure TOTP code is current (rotates every 30 seconds)
`ERR_SAML_DECODE`	400	`SAML_DECODE`	The SAML response could not be decoded	Ensure SAML response is properly Base64-encoded valid XML

WhatsApp ErrorsWhatsApp

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_WHATSAPP_UNAVAILABLE`	503	`WHATSAPP_UNAVAILABLE`	WhatsApp media send failed	Verify META_WHATSAPP_ACCESS_TOKEN and META_WHATSAPP_PHONE_NUMBER_ID env vars
`ERR_INTEGRATION_HUB_SVC_WHATSAPP_NOT_CONFIGURED`	503	`WHATSAPP_NOT_CONFIGURED`	WhatsApp Business API credentials are not configured	Set META_WABA_ID and META_WHATSAPP_ACCESS_TOKEN env vars
`ERR_INTEGRATION_HUB_SVC_WHATSAPP_SYNC_FAILED`	503	`WHATSAPP_SYNC_FAILED`	Template synchronization from Meta failed	Verify META_WABA_ID and whatsapp_business_management permission
`ERR_INTEGRATION_HUB_SVC_WHATSAPP_MEDIA_DOWNLOAD_FAILED`	503	`WHATSAPP_MEDIA_DOWNLOAD_FAILED`	Media download and S3 storage failed	Check mediaId validity (Meta URLs are temporary). Verify S3 permissions.
`ERR_INTEGRATION_HUB_DELIVERY_NOT_FOUND`	403	`DELIVERY_NOT_FOUND`	Message delivery record not found	Verify messageId. Can be Meta ID or internal delivery record ID.
`ERR_INTEGRATION_HUB_INVALID_SIGNATURE`	401	`INVALID_SIGNATURE`	WhatsApp webhook HMAC-SHA256 signature verification failed	Verify META_WEBHOOK_APP_SECRET matches Meta app configuration
`ERR_INTEGRATION_HUB_TEMPLATE_REQUIRED`	400	`TEMPLATE_REQUIRED`	Template required (24h messaging window closed)	Include template_name in request. Only Meta-approved templates allowed.
`ERR_INTEGRATION_HUB_TEMPLATE_NOT_FOUND`	404	`TEMPLATE_NOT_FOUND`	WhatsApp template not found	Sync templates using POST /whatsapp/templates/sync. Names are case-sensitive.
`ERR_INTEGRATION_HUB_INVALID_TEMPLATE_PARAMS`	400	`INVALID_TEMPLATE_PARAMS`	Template parameters do not match definition	Check template definition for required parameters via GET /whatsapp/templates
`ERR_INTEGRATION_HUB_INVALID_PHONE`	400	`INVALID_PHONE`	Phone number format is invalid	Use E.164 format: +<country_code><number> (e.g., +14155552671)

Storage / IPFS ErrorsStorage

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_IPFS_UNAVAILABLE`	503	`IPFS_UNAVAILABLE`	IPFS service is unavailable	Verify IPFS node connectivity. Check gateway config and API credentials.

Integration & Marketplace ErrorsIntegration

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_INTEGRATION_NOT_FOUND`	404	`INTEGRATION_NOT_FOUND`	The specified integration was not found	Use GET /integrations/installed or GET /marketplace/integrations to verify ID
`ERR_CONNECTION_NOT_FOUND`	404	`CONNECTION_NOT_FOUND`	The specified OAuth connection was not found	Use GET /connections to list connections. Connections are tenant-scoped.
`ERR_WEBHOOK_NOT_FOUND`	404	`WEBHOOK_NOT_FOUND`	The specified webhook event was not found	Use GET /webhooks to list webhook events for the current tenant

API Versioning ErrorsVersioning

Code	HTTP	Name	Description	Resolution
`ERR_INTEGRATION_HUB_SVC_UNSUPPORTED_API_VERSION`	400	`UNSUPPORTED_API_VERSION`	The requested API version is not recognized	Use v1 (current) or v2. Check supportedVersions in error response.
`ERR_INTEGRATION_HUB_SVC_API_VERSION_SUNSET`	400	`API_VERSION_SUNSET`	The API version has been permanently removed	Migrate to current version. See migrationGuide URL in error response.

Authentication & AuthorizationAuth

Code	HTTP	Name	Description	Resolution
`ERR_TENANT_REQUIRED`	401	`TENANT_REQUIRED`	Tenant ID is missing from the request	Include x-tenant-id header with a valid UUID
`ERR_RBAC_FORBIDDEN`	403	`RBAC_FORBIDDEN`	User has no roles assigned	Ensure user has user, organizer, or admin role in JWT
`ERR_MTLS_REQUIRED`	401	`MTLS_REQUIRED`	mTLS client certificate verification failed	Internal endpoints require valid mTLS certificate via API gateway
`ERR_RATE_LIMIT_EXCEEDED`	429	`RATE_LIMIT_EXCEEDED`	Per-minute rate limit exceeded	Wait for retryAfter seconds. Implement exponential backoff.
`ERR_UNEXPECTED`	500	`UNEXPECTED`	An unhandled exception occurred	Check logs with x-request-id. Report to platform team if persistent.

Meta WhatsApp AdapterMeta Adapter

Code	HTTP	Name	Description	Resolution
`META_UNAUTHORIZED`	401	`META_UNAUTHORIZED`	Invalid Meta OAuth access token (error 190)	Refresh the Meta WhatsApp access token
`META_INVALID_PARAM`	400	`META_INVALID_PARAM`	Invalid parameter in Meta API request (error 100)	Check message payload for invalid fields. Verify phone format.
`META_UNDELIVERABLE`	400	`META_UNDELIVERABLE`	Message could not be delivered (error 131048)	Verify recipient is registered on WhatsApp and has not blocked the business
`META_TEMPLATE_NOT_FOUND`	404	`META_TEMPLATE_NOT_FOUND`	Message template not found (error 133000)	Sync templates using POST /whatsapp/templates/sync
`META_TEMPLATE_PAUSED`	400	`META_TEMPLATE_PAUSED`	Template paused by Meta due to low quality (error 132000)	Create a new template or improve the existing template quality
`META_RATE_LIMIT`	429	`META_RATE_LIMIT`	Meta API rate limit exceeded (error 4)	Implement backoff and retry. Check WhatsApp Business API tier.