Agentic Commerce Errors

DEPRECATED

This reference applies to the deprecated Agents, Enrollments, and Instructions API, which remains available for existing integrations. New Agentic Payments integrations should use Errors and Recovery. No removal date has been announced.

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	The card brand is not supported. Visa and Mastercard are the supported brands.
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	The provider has not approved the instruction yet.
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	The card network suspended or removed the underlying token, so the instruction was cancelled. Deleting an instruction removes it outright — a later request returns 404, not this code.
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.
AUTOFILL_NOT_VERIFIABLE	400	Verification is not applicable to autofill enrollments	Called a verification endpoint on an autofill enrollment.
AUTOFILL_NOT_CONFIRMABLE	400	Transaction confirmation is not applicable to autofill instructions	Called confirm on an autofill instruction.
INVALID_OTP	400	The OTP code is invalid or expired	Wrong OTP code submitted.
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.
CARD_NOT_ELIGIBLE	400	Card is not eligible for enrollment	Rejected by eligibility rules before any network call — a non-US issuer country, a prepaid or commercial card, or an unsupported issuer.
VERIFICATION_NOT_SUPPORTED	422	Verification is not supported for this card	The card cannot complete the requested ceremony.
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.
AUTOFILL_NOT_AVAILABLE	403	Autofill is not available for this tenant	Tenant is not enabled for autofill enrollments.
AGENT_NOT_FOUND	404	Agent not found	Agent ID doesn't exist or belongs to a different tenant.
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_VERIFICATION_FAILED	422	Verification failed at provider	Unexpected error from card network during OTP/passkey verification.

Server Errors (5XX)

Type	HTTP	Title	When
INTERNAL_ERROR	500	Internal server error	Unexpected server error.
PROVIDER_INSTRUCTION_CANCEL_FAILED	500	Internal server error	Visa instruction cancellation failed or could not be confirmed. The instruction or allowance remains active locally; repeat the same DELETE, then contact support if it persists.
PROVIDER_CONFIRMATION_FAILED	500	Internal server error	Visa transaction confirmation failed or could not be confirmed. Preserve the confirmation data and contact support before submitting a new confirmation.