Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.seismic-cards.systems/llms.txt

Use this file to discover all available pages before exploring further.

When the Seismic Cards API rejects a request or encounters a problem, it returns a consistent error envelope with a stable numeric code and a human-readable message: 
{
  "code": "40001",
  "message": "Invalid parameter"
}
The HTTP status is 4xx for errors you can correct and 5xx for temporary server-side failures. Always pattern-match on code in your code — never on message, because messages may be reworded across versions while codes remain stable.

​
How to read a code

All codes are 5-digit strings (or 6-digit for field-level errors). The leading digits indicate the class of error:
RangeClass
00000 – 00099Success / informational
01xxxx – 09xxxxField-level validation
40xxxAuthentication / authorization
100xxx – 199xxxResource lifecycle (cardholder, card, KYC)
9xxxxInternal server / dependency errors
The first two digits of most codes mirror the HTTP status — for example, 40001 maps to HTTP 400 and 40399 maps to HTTP 403.

​
Common errors

CodeHTTPMeaningLikely cause
000000200Success—
40001400Invalid parameterA required field is missing or malformed. The message will name the field.
40002400Validation failedA field passed type checks but failed semantic validation (e.g. invalid country code).
40003400Idempotency key reuseThe same Idempotency-Key was sent with a different request body. Use a fresh UUID.
40004400Reference ID already usedYour referenceId for a cardholder or card already exists. Generate a new one.
40101401UnauthorizedMissing or expired x-access-token. Re-run the OAuth flow to get a new token.
40399403Permission deniedThe token is for a different program or environment.
40404404Resource not foundThe accountId, cardholderId, budgetId, or cardId doesn’t exist or doesn’t belong to your program.
40499404Endpoint not foundPath typo or wrong API version.
40901409Conflict / duplicateFor example, the email already exists for your parentAccountId.
40903409Cardholder email mismatchThe cardholder belongs to a different sub-account or has a different email.
42901429Rate limit exceededBack off and retry with exponential delay.
50000500Internal server errorRetry with the same Idempotency-Key. If the error persists, contact support.
50301503Service temporarily unavailableUpstream issuer or network outage. Retry after a short delay.

​
KYC / cardholder errors

The cardholder profile already exists with a different referenceId. Look it up via GET /v1/cardholders and reuse its id instead of creating a new cardholder.
A cardholder PATCH request must include email for BB / BZ BINs. Add the email field to your request body.
The phone number failed libphonenumber validation. Check that phoneCountryCode contains digits only (no +) and that the phone number itself is valid.
firstName + " " + lastName must be 23 characters or fewer. Abbreviate the name to fit within the limit.
Names must use A–Z / a–z only. Strip diacritics (e.g. é → e) and punctuation before submitting.
The sourceType you sent is unknown. Use "sumsub" or contact support to confirm which sources are enabled for your program.
The sumsubShareToken is expired or was issued for a different applicant. Generate a fresh share token from Sumsub and retry.
The user has already passed KYC. No action is needed — you can proceed to initialize the account.

​
Card lifecycle errors

CodeMeaningAction
020001BIN not available for accountPass the correct binId from GET /v1/card/bins.
020002Cardholder not approvedWait for the CARDHOLDER.UPDATED webhook with status APPROVED before issuing a card.
020003Account not initializedCall POST /v1/accounts/{accountId}/init after KYC approval, then retry.
020004Budget balance insufficient for issuanceSome BINs require a minimum opening balance. Fund the budget first, then issue the card.
020005Card limit reachedYour program’s per-user maximum has been reached. Contact support to discuss your limits.
020010Card already deletedThe operation was skipped because the card is already closed.
020011Card already frozen / unfrozenThe operation was skipped (idempotent). The card is already in the state you requested.

​
Funding errors

CodeMeaningAction
030001Insufficient balanceThe source wallet (USD Wallet or budget) doesn’t have enough funds. Top up before retrying.
030002Currency mismatchThe source and destination must use the same currency.
030003Locked fundsThe amount you want to withdraw is locked by pending card authorizations. Wait for them to settle or reduce the withdrawal amount.

​
Webhook retry schedule

If your endpoint returns a non-2xx response, Seismic logs the failure and retries automatically on the following schedule:
AttemptDelay from previous
1Immediate
2+30 seconds
3+1 minute
4+5 minutes
5+15 minutes
6+1 hour
7+4 hours
8+24 hours (final)
After the final retry, the event moves to a dead-letter queue. You can replay any failed delivery from the sandbox dashboard for up to 30 days after the original event.
Respond to webhook deliveries with 200 OK as quickly as possible — ideally before doing any heavy processing. Enqueue the event and handle it asynchronously to avoid timeouts that trigger unnecessary retries.
See the Webhooks guide for event types, signatures, and payload shapes.

​
Best practices

  1. Pattern-match on code, not message. Messages may be reworded; codes are stable contracts.
  2. Retry on 5xx and 429 only. Errors in the 4xx range (except 429) won’t succeed on retry without changing the request.
  3. Always send a fresh Idempotency-Key when the request body changes. Reuse the same key only when retrying the exact same request.
  4. Log the full error envelope — code, message, response headers, and the request-id header — before opening a support ticket.
  5. Don’t expose internal codes to end users. Map error codes to human-friendly messages in your UI layer.

​
Need help?