Agentic Commerce Errors

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_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 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.