TokeniErrors
One envelope, opaque messages, a correlation ID you can send to support.
Every JSON error looks like this:
{
"success": false,
"errorCode": "INVALID_REQUEST",
"errorMessage": "Invalid card number",
"correlationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}errorMessage is safe to show in your own logs. It will not contain a PAN, a stack trace, or an internal host name.
Codes
| Code | When |
|---|---|
UNAUTHORIZED | Missing or wrong Basic credentials |
SIGNATURE_REQUIRED | Route needs X-Signature |
INVALID_SIGNATURE | HMAC did not match |
IP_NOT_WHITELISTED | Key is locked to other IPs |
RATE_LIMIT_EXCEEDED | Slow down |
INVALID_REQUEST | Body failed validation (Luhn, expiry, required fields) |
INVALID_TOKEN | Token format or state is not usable |
MISSING_FIELD | Required field absent |
TOKEN_NOT_FOUND | Unknown or not yours |
TRANSACTION_NOT_FOUND | Unknown or not yours |
PROFILE_NOT_FOUND | Unknown or not yours |
TOKENIZATION_FAILED | Vault rejected the tokenize |
TRANSACTION_FAILED | Processor or gateway declined |
DUPLICATE_REQUEST | Idempotency key replay |
CLOCK_SKEW | Date header too far from server time |
INTERNAL_ERROR | Ours. Retry with a new idempotency key only if the original never committed |
SERVICE_UNAVAILABLE | Backing service down |
Validation
- PAN: 13–19 digits, Luhn, numeric
- CVV: 3–4 digits, numeric, never persisted
- Expiry: month 01–12, not expired
Malformed input gets INVALID_REQUEST, not a parser dump.