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
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:- Duplicate
external_idwhen creating a customer - Duplicate name for a unique resource
- Attempting to transition to an invalid state
- Concurrent modification conflict
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
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.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 and retry. 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, and a closed card cannot be changed.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: Sandbox only. The simulated card cannot present a transaction because it is not active.Resolution: Activate or unfreeze the card before simulating a purchase.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:
400) are cached, 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

