200 from 401 authentication failure and 503 unavailable eligibility. See Foreign exchange (FX) for availability and quote error guidance.
Error Response Format
All errors return a JSON response with theapplication/problem+json content type:
Response Fields
detail is optional and not guaranteed on every error. Some pre-validation rejections — for example a missing X-Idempotency-Key or malformed JSON — are rejected before the request body is processed and may return a 4xx with an empty or minimal body. Do not assume detail (or errors) is always present; branch on status and type first, and quote request_id when contacting support.Validation Errors
When a request fails validation, the response includes anerrors array with field-level details:
HTTP Status Codes
Error Types Reference
Each error type has a unique URI that identifies the problem category. Thetype field in every error response links directly to the corresponding section below.
Client Errors (4xx)
validation-error
validation-error
400 Bad RequestDescription: One or more request fields failed validation. Check the errors array for specific field-level details.Example Response:- Missing required fields in the request body
- Invalid field format (e.g., malformed email, invalid phone number)
- Invalid enum values
- Field value out of allowed range
errors array and correct each field according to the API specification.invalid-request
invalid-request
400 Bad RequestDescription: The request could not be processed due to malformed syntax or invalid content.Example Response:- Malformed JSON in request body
- Invalid Content-Type header
- Missing required headers
- Request body too large
- An invalid developer fee, such as sending both
developer_fee_bpsanddeveloper_fee_fixed. See Developer fee errors for each message.
detail names.invalid-identifier
invalid-identifier
400 Bad RequestDescription: One or more resource identifiers in the request are malformed or invalid.Example Response:- Invalid KSUID format in path or query parameters
- Using an identifier from a different resource type
- Malformed UUID or prefixed ID
insufficient-balance
insufficient-balance
400 Bad RequestDescription: The operation cannot be completed due to insufficient balance in the source account or wallet.Example Response:- Attempting to transfer more than available balance
- Balance reserved for pending transactions
- Network fees not accounted for in available balance
limit-reached
limit-reached
400 Bad RequestDescription: A configured resource limit has been reached for your organization.Example Response:- Maximum API keys created
- Maximum webhook targets configured
- Resource quota exceeded
multiple-clients
multiple-clients
400 Bad RequestDescription: The authenticated user has access to multiple clients. You must specify which client to use.Example Response:authentication-error
authentication-error
401 UnauthorizedDescription: Authentication credentials are missing, invalid, or expired.Example Response:- Missing
x-api-keyheader - Invalid or revoked API key
- Expired application token
- Malformed authentication header
x-api-key header is properly formatted.forbidden
forbidden
403 ForbiddenDescription: Your credentials are valid but you do not have permission to perform this action.Example Response:- Accessing a resource belonging to another organization
- API key lacks required scopes
- User role insufficient for the operation
- Resource access restricted by policy
account-under-review
account-under-review
403 ForbiddenDescription: The customer’s account is under review and cannot move funds until the review is resolved. It is returned by the endpoints that start or set up money movement for the customer, including transaction creation, account creation and update, recipient and destination creation, wallet creation and wallet transactions, FX quotes, payment agents, proposals and scheduled payments, and x402.Example Response:frozen is reported by customer.kyb_status.updated; a freeze without a KYB status change sends no such event. The customer.capability_status.updated event follows a freeze only on the next capability recompute, so it can lag the freeze.Account creation: an open freeze blocks creating any account. An operator account status can also block it: an onramp account needs a status that permits receiving funds, an offramp account one that permits sending, and a swap account is checked against the freeze only.Resolution: Wait for the review to be resolved, or contact Dakota support.state-restricted-rd
state-restricted-rd
403 ForbiddenDescription: The requested onramp or swap account would deal in RD, but RD is not available in the customer’s US state.Example Response:USDC) for affected customers, or contact Dakota if you believe the customer’s state has been resolved incorrectly.not-found
not-found
404 Not FoundDescription: The requested resource does not exist or has been deleted.Example Response:- Resource was deleted
- Incorrect resource ID
- Resource belongs to a different organization
- Typo in the resource path
conflict
conflict
409 ConflictDescription: The request conflicts with the current state of the resource.Example Response:- Creating or renaming a recipient to a name the customer already uses (compared ignoring case and surrounding whitespace)
- Duplicate name for another unique resource
- Attempting to transition to an invalid state
- Concurrent modification conflict
external_id is not unique and never causes a 409.payload-too-large
payload-too-large
413 Payload Too LargeDescription: The request payload exceeds the maximum allowed size.Example Response:- File upload exceeds 500 MB limit
- Request body too large
- Bulk operation with too many items
idempotency-key-reused
idempotency-key-reused
422 Unprocessable EntityDescription: The x-idempotency-key was already used on this endpoint, within the last 24 hours, with a different request body. The request was not executed and the original response was not replayed. The 422 means a request with this key already reached Dakota and was processed. Do not resubmit under a new key until you have checked whether the original request succeeded, or the operation may run twice.Example Response:- A key reused for a new operation instead of a new UUID per logical request
- A retry that regenerated a field in the body (a timestamp, nonce or amount)
- A static key copied from a Postman collection or test script
compliance-blocked
compliance-blocked
422 Unprocessable EntityDescription: The request cannot be completed due to compliance restrictions.Example Response:- Destination wallet address flagged by compliance screening
- Transaction blocked by sanctions screening
- Customer flagged for compliance review
- Geographic restrictions
rate-limited
rate-limited
429 Too Many RequestsDescription: You have exceeded the rate limit for API requests.Example Response:Retry-After header.Cards Errors
Cards is available in sandbox only. See Cards.cards-tos-not-accepted
cards-tos-not-accepted
403 ForbiddenDescription: The customer has not accepted the Cards terms, and nothing else is outstanding. resolution_url carries the terms link.Resolution: Send the customer the terms link from GET /customers/{customer_id}/capabilities. See Activating customers.cards-capability-enabling
cards-capability-enabling
403 ForbiddenDescription: The customer has completed what Cards require, and Dakota is finishing the Cards setup. Nothing is needed from you or the customer. errors can still list optional items that do not block Cards.Resolution: Retry once customer.capability_status.updated reports cards as available, rather than polling. Contact Dakota if it does not complete. See Activating customers.cardholder-base-not-enabled
cardholder-base-not-enabled
403 ForbiddenDescription: Your account is not activated to issue cards to this type of customer (business or individual).Resolution: Contact Dakota.cards-consumer-base-disabled
cards-consumer-base-disabled
422 Unprocessable EntityDescription: Cards for individual customers are not available in this environment.Resolution: Contact Dakota.cardholder-person-exists
cardholder-person-exists
409 ConflictDescription: The email in the request belongs to a person already on the customer’s onboarding application. person_id names them when known.Resolution: Retry with that person_id. Without one, use a different email.cardholder-already-exists
cardholder-already-exists
409 ConflictDescription: A cardholder already exists for this person or email. An individual customer can have only one cardholder.Resolution: Use the cardholder named by cardholder_id.cardholder-reenroll-required
cardholder-reenroll-required
409 ConflictDescription: The cardholder was enrolled before the card program’s current requirements applied, so no new card can be issued to it.Resolution: Close its cards, delete the cardholder, and create it again.cardholder-not-active
cardholder-not-active
403 ForbiddenDescription: Cards can only be issued to an active cardholder. detail reports the cardholder’s status.Resolution: Wait for cardholder.updated with status: active.cardholder-suspended
cardholder-suspended
403 ForbiddenDescription: The cardholder is suspended, so its cards cannot be unfrozen. Freezing and closing still work.Resolution: Only Dakota can lift a suspension.cardholder-information-rejected
cardholder-information-rejected
422 Unprocessable EntityDescription: A submitted answer does not fit an open request on the cardholder’s application.Resolution: Check the request items with GET /cardholders/{cardholder_id}/application.cardholder-review-not-available
cardholder-review-not-available
501 Not ImplementedDescription: Answering review requests is not available yet.Resolution: None needed until the review process is switched on.wallet-not-card-enabled
wallet-not-card-enabled
403 ForbiddenDescription: The wallet has no active card enablement, so cards cannot be issued against it.Resolution: Enable the wallet and wait for wallet.card_enablement.completed.wallet-family-not-supported
wallet-family-not-supported
422 Unprocessable EntityDescription: Cards work with EVM wallets only.Resolution: Use an EVM wallet.card-enablement-precondition
card-enablement-precondition
409 ConflictDescription: A precondition for enabling the wallet was not met. errors[0].code names it.Resolution: For no_customer_policy, customer_policy_ambiguous, or customer_policy_shared, fix the wallet’s policies, then submit a new intent with a new idempotency_key, signed again. Replaying the refused request returns a plain 409 conflict for 24 hours: see Retrying a failed attempt. For any other code, contact Dakota.card-enablement-conflict
card-enablement-conflict
409 ConflictDescription: The request disagrees with the enablement already recorded for this wallet.Resolution: See Retrying a failed attempt.card-closed
card-closed
403 ForbiddenDescription: The card is closed. Closing is permanent: a closed card stays readable, but it cannot be changed or revealed.Resolution: Issue a new card.card-freeze-held
card-freeze-held
403 ForbiddenDescription: The card cannot be unfrozen: a freeze you cannot lift is holding it. errors names each source.Resolution: Read the card’s freeze_sources. Only manual freezes can be lifted through the API.card-not-activated
card-not-activated
403 ForbiddenDescription: status: active was sent for a card that is not activated yet. No change in the request was applied.Resolution: Retry after card.updated reports the card active. Contact Dakota if it stays inactive.card-not-active
card-not-active
409 ConflictDescription: The card is not active, so the request cannot run in its current state. It is returned in two cases:POST /cards/{card_id}/reveal_sessionon a card that is notactive, for examplependingorfrozen. Only an active card’s details can be revealed.detailnames the card’s status. A closed card returnscard-closedinstead.- Sandbox only: a simulated purchase on a card that is not
active.
pending card, wait for card.updated to report it active. For a frozen card, unfreeze it with PATCH /cards/{card_id}, then retry.cardholder-has-open-cards
cardholder-has-open-cards
409 ConflictDescription: DELETE /cardholders/{cardholder_id} was refused because the cardholder still has cards that are not closed (active, frozen or pending). Nothing was changed. errors names each blocking card: field is card_id, message is the card’s id, and code is card_<status>, for example card_frozen. Up to 50 cards are listed, and detail gives the total.PATCH /cards/{card_id} and status: closed, then retry the delete.spend-limit-rejected
spend-limit-rejected
400 Bad RequestDescription: The card program refused the requested spend limit. It is returned by POST /customers/{customer_id}/cards, PATCH /cards/{card_id} and PUT /cards/{card_id}/spend_limit, and errors names spend_limit with the code spend_limit_rejected. Nothing in the request was applied, and the card keeps its current limit. On card creation this replaces the generic invalid-request for this one case.Resolution: Choose a different amount or interval and retry. Retrying the same limit fails again.sandbox-card-simulation-daily-limit
sandbox-card-simulation-daily-limit
429 Too Many RequestsDescription: Sandbox only. Your account used its daily allowance of card simulations.Resolution: Wait for the allowance to restore, within 24 hours.Server Errors (5xx)
internal-error
internal-error
500 Internal Server ErrorDescription: An unexpected error occurred on the server. The error details are sanitized for security.Example Response:request_id.not-implemented
not-implemented
501 Not ImplementedDescription: The requested endpoint or feature is not yet implemented.Example Response:provider-error
provider-error
502 Bad GatewayDescription: An upstream provider returned an error.Example Response:Error Handling Best Practices
Basic Error Handler
Retry Logic with Exponential Backoff
For transient errors (5xx, rate limits), implement exponential backoff:Idempotency for Safe Retries
ForPOST, PUT, and PATCH requests, always include the x-idempotency-key header to safely retry failed requests. The key must be a valid UUID:
X-Idempotent-Replayed: true) instead of running the operation again, once the first request has completed. Dakota takes no lock while the first request is still running, so a retry sent before the first response arrives can run the operation a second time; wait for the response (or check the resource’s state) before retrying. If Dakota’s key store is briefly unavailable, requests are processed without the duplicate check. Bodies are compared as JSON, so a different key order or whitespace is the same request. Only successful responses (status below 400) are remembered, so a failed request stays retryable under the same key.
Troubleshooting
Getting Help
When contacting support about an error:- Always include the
request_idfrom the error response - Provide the full error response body
- Include the request method, path, and relevant headers (redact the API key)
- Describe what you expected vs. what happened
Common Issues
400 Validation Error with no details
400 Validation Error with no details
- Check the
errorsarray in the response for field-level details - Verify your
Content-Typeheader isapplication/json - Ensure the request body is valid JSON
- Compare your request against the OpenAPI specification
429 Rate Limited frequently
429 Rate Limited frequently
- Check
X-RateLimit-Remainingheader to monitor usage - Implement request batching where possible
- Add caching for frequently accessed resources
- Consider using webhooks instead of polling

