Send one Authorization: Bearer credential. It defines App, environment, audience and permissions.
Optional scope headers must appear together and match the credential. POST bodies use application/json. Default body limit: 16 KiB; customer write bodies, including attributes, are limited to 32 KiB.
Standard customer and commerce API responses carry requestId and scope. Errors use { requestId, error: { code, message, retryable, recovery, retryAfterSeconds? } }; X-Request-Id identifies the same diagnostic request. Responses are no-store. Messages are for display; branch on code and recovery.
The SDK does not follow redirects or retry automatically. It uses a 10-second timeout including response-body reading. Reuse stable requestId, eventId or idempotencyKey for a write retry.
HTTP errors
HTTP
Code
Meaning
400
INVALID_PROTOCOL_VERSION
Protocol headers are malformed or the SDK and protocol versions disagree.
400
UNSUPPORTED_PROTOCOL_VERSION
This protocol is not supported by the deployed service.
400
INVALID_REQUEST
The request body or parameters do not match the contract.
401
UNAUTHENTICATED
The credential is missing, invalid, expired or revoked.
403
FORBIDDEN
The credential lacks permission or the browser origin is not allowed.
403
SCOPE_MISMATCH
The scope headers do not match the credential’s App and environment.
404
NOT_FOUND
The object does not exist in the current App and environment.
409
CONFLICT
The request conflicts with existing data, for example different content under the same eventId.
410
PROTOCOL_RETIRED
This protocol has reached its published end-of-support date. Follow the migration notice before retrying.
413
PAYLOAD_TOO_LARGE
The request exceeds the endpoint’s body-size limit.
429
RATE_LIMITED
The request rate exceeds the limit; retry later.
500
INTERNAL_ERROR
An internal failure or invalid response occurred. Internal exception details are not exposed.
501
NOT_CONFIGURED
The App and environment are missing required integration configuration.
501
CAPABILITY_UNAVAILABLE
The current runtime or execution mode does not offer this operation; retries cannot enable it.
503
SERVICE_UNAVAILABLE
The service is temporarily unavailable; retry later.
HTTP errors
INVALID_PROTOCOL_VERSION400
Meaning
Protocol headers are malformed or the SDK and protocol versions disagree.
UNSUPPORTED_PROTOCOL_VERSION400
Meaning
This protocol is not supported by the deployed service.
INVALID_REQUEST400
Meaning
The request body or parameters do not match the contract.
UNAUTHENTICATED401
Meaning
The credential is missing, invalid, expired or revoked.
FORBIDDEN403
Meaning
The credential lacks permission or the browser origin is not allowed.
SCOPE_MISMATCH403
Meaning
The scope headers do not match the credential’s App and environment.
NOT_FOUND404
Meaning
The object does not exist in the current App and environment.
CONFLICT409
Meaning
The request conflicts with existing data, for example different content under the same eventId.
PROTOCOL_RETIRED410
Meaning
This protocol has reached its published end-of-support date. Follow the migration notice before retrying.
PAYLOAD_TOO_LARGE413
Meaning
The request exceeds the endpoint’s body-size limit.
RATE_LIMITED429
Meaning
The request rate exceeds the limit; retry later.
INTERNAL_ERROR500
Meaning
An internal failure or invalid response occurred. Internal exception details are not exposed.
NOT_CONFIGURED501
Meaning
The App and environment are missing required integration configuration.
CAPABILITY_UNAVAILABLE501
Meaning
The current runtime or execution mode does not offer this operation; retries cannot enable it.
SERVICE_UNAVAILABLE503
Meaning
The service is temporarily unavailable; retry later.
Client errors
Code
Meaning
NOT_IDENTIFIED
Call identify with a customer token before requesting customer data.
INVALID_TOKEN
The token is empty or a server key was supplied to the browser client.
SERVER_ONLY
The server client was constructed in a browser.
TIMEOUT
The request timed out (10 seconds by default; configurable from 1–120,000 ms).
NETWORK_ERROR
The network request failed. The SDK does not retry automatically.
IDENTITY_CHANGED
The identity changed or reset was called during the request; the old response was discarded.
SCOPE_MISMATCH
The response’s App or environment does not match the configured scope.
INVALID_REQUEST
Local validation rejected the method parameters.
INVALID_RESPONSE
The server response does not match the contract.
PROTOCOL_MISMATCH
The response protocol does not match this SDK; check supported protocols and versions.
HTTP_ERROR
The server returned an error response that could not be parsed.
INVALID_URL
baseUrl must use HTTPS (localhost HTTP is allowed) and contain no credentials or query parameters.
INVALID_TIMEOUT
timeoutMs must be between 1 and 120,000 milliseconds.
Client errors
NOT_IDENTIFIED
Meaning
Call identify with a customer token before requesting customer data.
INVALID_TOKEN
Meaning
The token is empty or a server key was supplied to the browser client.
SERVER_ONLY
Meaning
The server client was constructed in a browser.
TIMEOUT
Meaning
The request timed out (10 seconds by default; configurable from 1–120,000 ms).
NETWORK_ERROR
Meaning
The network request failed. The SDK does not retry automatically.
IDENTITY_CHANGED
Meaning
The identity changed or reset was called during the request; the old response was discarded.
SCOPE_MISMATCH
Meaning
The response’s App or environment does not match the configured scope.
INVALID_REQUEST
Meaning
Local validation rejected the method parameters.
INVALID_RESPONSE
Meaning
The server response does not match the contract.
PROTOCOL_MISMATCH
Meaning
The response protocol does not match this SDK; check supported protocols and versions.
HTTP_ERROR
Meaning
The server returned an error response that could not be parsed.
INVALID_URL
Meaning
baseUrl must use HTTPS (localhost HTTP is allowed) and contain no credentials or query parameters.
INVALID_TIMEOUT
Meaning
timeoutMs must be between 1 and 120,000 milliseconds.
Catch IndianaError and record code, status and requestId. Follow recovery: retry_same_request reuses the original business idempotency key and input after the indicated wait; reload_state reads current state; recover_operation reads the original operation before another attempt. Keep diagnostic requestId separate from business identifiers. The SDK does not retry writes automatically. Never log credentials; renew expired customer sessions through your authenticated backend.
Read an error response
The fields below apply to source protocol 0.5. See version information for publication status, SDK requirements and HTTP integration.
1{2"requestId": "<diagnostic-request-id>",3"error": {4"code": "CONFLICT",5"message": "The original request is still in progress.",6"retryable": true,7"recovery": "retry_same_request",8"retryAfterSeconds": 3,9"reason": "OPERATION_IN_PROGRESS"10 }11}
The example uses HTTP 425, Retry-After: 3 and an X-Request-Id matching requestId. Display message and branch on code/recovery. reason is optional; do not infer it from message. retryAfterSeconds is provided only for retryable errors with timing information. CLI JSON output places requestId inside error.
Status distinctions for a code
HTTP
code
Handling
501
NOT_CONFIGURED / CAPABILITY_UNAVAILABLE
The former needs configuration; the latter is not enabled in the current runtime and cannot be enabled by replacing credentials.
409 / 412
CONFLICT
Inspect the conflict or reload state; code alone does not establish retryability. Stale-state responses normally use 409; some management adapters retain 412.
425
CONFLICT
The original attempt is in progress; wait, then reuse its identity and input.
429
RATE_LIMITED
Back off as directed without creating another business operation.
408 / 502 / 503 / 504
SERVICE_UNAVAILABLE
Follow retryable / recovery. RESULT_UNKNOWN requires original-operation recovery even with HTTP 503. Without a readable error body, the SDK may return HTTP_ERROR.
500
INTERNAL_ERROR
Does not prove rollback; read or recover the original operation first.
Status distinctions for a code
501
code
NOT_CONFIGURED / CAPABILITY_UNAVAILABLE
Handling
The former needs configuration; the latter is not enabled in the current runtime and cannot be enabled by replacing credentials.
409 / 412
code
CONFLICT
Handling
Inspect the conflict or reload state; code alone does not establish retryability. Stale-state responses normally use 409; some management adapters retain 412.
425
code
CONFLICT
Handling
The original attempt is in progress; wait, then reuse its identity and input.
429
code
RATE_LIMITED
Handling
Back off as directed without creating another business operation.
408 / 502 / 503 / 504
code
SERVICE_UNAVAILABLE
Handling
Follow retryable / recovery. RESULT_UNKNOWN requires original-operation recovery even with HTTP 503. Without a readable error body, the SDK may return HTTP_ERROR.
500
code
INTERNAL_ERROR
Handling
Does not prove rollback; read or recover the original operation first.
Recovery actions
Choose the next action by recovery
recovery
Next action
fix_request
Correct the request instead of repeatedly resubmitting it.
authenticate
Restore credentials for the current identity through the host backend; do not switch Customer to bypass a refusal.
check_permissions
Check current roles, grants and operation permissions.
check_scope
Check the App and environment bound to the credential.
resolve_conflict
Inspect the conflicting request or state; a 409 does not authorize a blind retry.
reload_state
Read the current version and review the edit before submitting again.
retry_same_request
Wait as directed by Retry-After, then reuse the original business idempotency key and identical input without creating another operation.
configure_integration
Configure the integration for this App and environment first; repeated requests do not enable it.
check_availability
Check capabilities and supported scope; retries cannot enable an unavailable operation.
upgrade_sdk
Check supported server protocols and SDK versions, then follow the release instructions.
recover_operation
The outcome may be unknown. Read or recover the original operation with its persisted business ID before deciding what to do, especially before another payment.
contact_support
Retain the code, HTTP status and diagnostic requestId for the administrator or support team.
Choose the next action by recovery
fix_request
Next action
Correct the request instead of repeatedly resubmitting it.
authenticate
Next action
Restore credentials for the current identity through the host backend; do not switch Customer to bypass a refusal.
check_permissions
Next action
Check current roles, grants and operation permissions.
check_scope
Next action
Check the App and environment bound to the credential.
resolve_conflict
Next action
Inspect the conflicting request or state; a 409 does not authorize a blind retry.
reload_state
Next action
Read the current version and review the edit before submitting again.
retry_same_request
Next action
Wait as directed by Retry-After, then reuse the original business idempotency key and identical input without creating another operation.
configure_integration
Next action
Configure the integration for this App and environment first; repeated requests do not enable it.
check_availability
Next action
Check capabilities and supported scope; retries cannot enable an unavailable operation.
upgrade_sdk
Next action
Check supported server protocols and SDK versions, then follow the release instructions.
recover_operation
Next action
The outcome may be unknown. Read or recover the original operation with its persisted business ID before deciding what to do, especially before another payment.
contact_support
Next action
Retain the code, HTTP status and diagnostic requestId for the administrator or support team.
retryable=true does not make the SDK or CLI resend automatically or authorize a new idempotency key. TIMEOUT, NETWORK_ERROR, unreadable responses and generic 500s do not prove a write failed. Record the diagnostic requestId separately from the business requestId, eventId or idempotencyKey.
Business reasons
Safe classifications for optional reason
reason
Handling
CAPABILITY_NOT_ENABLED
The current runtime does not enable this operation; check its supported scope.
INTEGRATION_MISSING
Configure the integration for this App and environment first.
PROVIDER_CREDENTIAL_REJECTED
Provider credentials are unavailable; follow recovery to correct configuration or recover a transient failure.
PRICE_BINDING_REQUIRED
Correct the Product / Price provider binding or billing configuration.
IDEMPOTENCY_CONFLICT
An existing operation owns this idempotency identity; inspect its original input and result.
RESULT_UNKNOWN
The original operation may have taken effect; read or recover it before another write.
STATE_CHANGED
The state or version changed; reload and review the current state.
OPERATION_IN_PROGRESS
The original operation or its provider record is still in progress; wait as directed and recover that operation.
FUNNEL_VERSION_RETIRED
This Funnel Version uses a retired format and can no longer start or continue; publish a new Version in the Console.
Safe classifications for optional reason
CAPABILITY_NOT_ENABLED
Handling
The current runtime does not enable this operation; check its supported scope.
INTEGRATION_MISSING
Handling
Configure the integration for this App and environment first.
PROVIDER_CREDENTIAL_REJECTED
Handling
Provider credentials are unavailable; follow recovery to correct configuration or recover a transient failure.
PRICE_BINDING_REQUIRED
Handling
Correct the Product / Price provider binding or billing configuration.
IDEMPOTENCY_CONFLICT
Handling
An existing operation owns this idempotency identity; inspect its original input and result.
RESULT_UNKNOWN
Handling
The original operation may have taken effect; read or recover it before another write.
STATE_CHANGED
Handling
The state or version changed; reload and review the current state.
OPERATION_IN_PROGRESS
Handling
The original operation or its provider record is still in progress; wait as directed and recover that operation.
FUNNEL_VERSION_RETIRED
Handling
This Funnel Version uses a retired format and can no longer start or continue; publish a new Version in the Console.
SDK diagnostic example
error-reference.tsTypeScript
1import { IndianaError } from"@tinkerlandai/indiana-sdk";23// Call from your catch block. Log references, never error.message or credentials.4exportfunctionerrorReference(error: unknown) {5if (!(error instanceof IndianaError)) {6return { code: "UNKNOWN_ERROR", retryable: false, recovery: "contact_support" };7 }8return {9 code: error.code,10 status: error.status,11 requestId: error.requestId,12 retryable: error.retryable,13 recovery: error.recovery,14 retryAfterSeconds: error.retryAfterSeconds,15 reason: error.reason,16 };17}18// Before retrying a write, use your persisted business operation ID to recover it.19// The diagnostic requestId above identifies an HTTP attempt, not its business effect.