Agentic Commerce Errors

All error responses follow RFC 7807 problem details format and include a BT-TRACE-ID response header for correlating requests with Basis Theory support.

Request Tracing

Every API response includes a BT-TRACE-ID header. The value is determined in this order:

1. Client-provided — if you send a BT-TRACE-ID request header, it is echoed back.
2. Cloudflare Ray ID — if no client header is present, the CF-Ray header from Cloudflare is used.
3. Auto-generated — if neither is available, a UUID is generated.

Include this value when contacting support to help trace issues.

Error Response Format

{
  "type": "PROVIDER_ENROLLMENT_FAILED",
  "title": "Card enrollment failed at provider",
  "status": 422,
  "detail": "An error occurred with the upstream provider. Contact support if the issue persists.",
  "debug": {
    "provider_correlation": "visa-corr-456"
  }
}

The debug field is included on provider errors (PROVIDER_*) when a provider correlation ID is available. This can be useful when working with Basis Theory support to trace issues back to the card network.

Client Errors (4XX)

Type	HTTP	Title	When
VALIDATION_ERROR	400	Request validation failed	Request body fails schema validation. The errors field contains per-field details.
INVALID_TOKEN	400	Invalid or inaccessible Basis Theory token	The token_id doesn't exist, is expired, or the API key lacks access.
UNSUPPORTED_PROVIDER	400	Card brand not supported	Card brand (e.g., Amex, Discover) isn't supported yet — only Visa and Mastercard currently.
VISA_RELATIONSHIP_ID_NOT_CONFIGURED	400	Visa relationship ID is not configured for this tenant	Tenant hasn't completed Visa onboarding.
AGENT_ENROLLMENT_LIMIT	400	Agent has reached the maximum number of enrollments (50)	Agent already has 50 enrollments linked.
ENROLLMENT_PENDING	400	Enrollment is pending cardholder approval	Enrollment exists but hasn't completed verification yet.
INSTRUCTION_PENDING	400	Instruction is pending cardholder approval	Instruction requires passkey verification before use.
INSTRUCTION_PENDING_VERIFICATION	400	Instruction requires verification before credentials can be retrieved	Instruction was approved by the provider but the consumer hasn't completed passkey verification yet.
INSTRUCTION_CANCELLED	400	Instruction has been cancelled	Instruction was soft-deleted or cancelled.
INSTRUCTION_EXPIRED	400	Instruction has expired	Instruction's expires_at has passed.
VERIFICATION_NOT_REQUIRED	400	Enrollment does not require verification	Called verify on an enrollment that was auto-approved.
VERIFICATION_STATE_INVALID	400	Verification state is invalid for this operation	Called an OTP/method/passkey endpoint out of order.
INVALID_OTP	400	The OTP code is invalid or expired	Wrong OTP code submitted.
OTP_EXPIRED	400	OTP code expired, please request a new code	OTP timed out — restart by calling the select method endpoint again.
MAX_ATTEMPTS_EXCEEDED	400	Too many failed attempts, please restart verification	Too many wrong OTP attempts — must restart the verification flow.
PASSKEY_FAILED	400	Passkey authentication failed	Passkey/FIDO assertion was invalid.
UNAUTHORIZED	401	Invalid or missing credentials	Missing or invalid BT-API-KEY header.
FORBIDDEN	403	Insufficient permissions	API key lacks the required permission for this endpoint.
ENROLLMENT_DELETED	403	Enrollment has been deleted	Attempted to use a soft-deleted enrollment.
ENROLLMENT_ACCESS_DENIED	403	Agent does not have access to this enrollment	Agent doesn't have this enrollment in its enrollment_ids.
ENROLLMENT_FAILED	422	Enrollment failed and must be retried before use	Enrollment is in failed status. Retry the enrollment before verifying or creating instructions.
ENROLLMENT_NOT_FAILED	400	Only failed enrollments can be retried	Called retry on an enrollment that isn't in failed status.
ENROLLMENT_PENDING_VERIFICATION	403	Cannot create instruction with unverified enrollment	Tried to create instruction before enrollment verification completed.
AGENT_NOT_FOUND	404	Agent not found	Agent ID doesn't exist or belongs to a different tenant.
KEY_NOT_FOUND	404	Key not found	Internal key lookup failed.
ENROLLMENT_NOT_FOUND	404	Enrollment not found	Enrollment ID doesn't exist or belongs to a different tenant.
INSTRUCTION_NOT_FOUND	404	Instruction not found	Instruction ID doesn't exist or belongs to a different agent.
ENROLLMENT_ALREADY_VERIFIED	409	Enrollment is already verified	Called verify on an enrollment that's already active.
CARD_REJECTED	422	Card was rejected by the card network	Card was declined, not eligible, or failed verification at the network. Try a different card.
PROVIDER_ENROLLMENT_FAILED	422	Card enrollment failed at provider	Unexpected error from card network during enrollment.
PROVIDER_INSTRUCTION_FAILED	422	Instruction creation failed at provider	Unexpected error from card network during instruction creation.
PROVIDER_INSTRUCTION_UPDATE_FAILED	422	Instruction update failed at provider	Unexpected error from card network during instruction update.
PROVIDER_CREDENTIALS_FAILED	422	Credential retrieval failed at provider	Unexpected error from card network during credential fetch.
PROVIDER_CONFIRMATION_FAILED	422	Confirmation publishing failed at provider	Unexpected error from card network during instruction confirmation.
PROVIDER_VERIFICATION_FAILED	422	Verification failed at provider	Unexpected error from card network during OTP/passkey verification.
PROVIDER_UNAVAILABLE	422	Provider service unavailable	Card network is down or unreachable. Retry with backoff.

Server Errors (5XX)

Type	HTTP	Title	When
INTERNAL_ERROR	500	Internal server error	Unexpected server error.