Skip to main content
The Dakota API uses RFC 9457 Problem Details for all error responses. This standardized format provides machine-readable error types, human-readable descriptions, and actionable details to help you handle errors programmatically.

Error Response Format

All errors return a JSON response with the application/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 an errors array with field-level details:
Validation Error Fields:

HTTP Status Codes


Error Types Reference

Each error type has a unique URI that identifies the problem category. The type field in every error response links directly to the corresponding section below.

Client Errors (4xx)

HTTP Status: 400 Bad RequestDescription: One or more request fields failed validation. Check the errors array for specific field-level details.Example Response:
Common Causes:
  • 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
Resolution: Review the errors array and correct each field according to the API specification.
HTTP Status: 400 Bad RequestDescription: The request could not be processed due to malformed syntax or invalid content.Example Response:
Common Causes:
  • 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_bps and developer_fee_fixed. See Developer fee errors for each message.
Resolution: Verify that your request body is valid JSON and includes all required headers. For a developer fee error, correct the field that detail names.
HTTP Status: 400 Bad RequestDescription: One or more resource identifiers in the request are malformed or invalid.Example Response:
Common Causes:
  • Invalid KSUID format in path or query parameters
  • Using an identifier from a different resource type
  • Malformed UUID or prefixed ID
Resolution: Ensure all identifiers are valid KSUIDs (27-character base62 strings) obtained from previous API responses.
HTTP Status: 400 Bad RequestDescription: The operation cannot be completed due to insufficient balance in the source account or wallet.Example Response:
Common Causes:
  • Attempting to transfer more than available balance
  • Balance reserved for pending transactions
  • Network fees not accounted for in available balance
Resolution: Check the account or wallet balance before initiating the transaction.
HTTP Status: 400 Bad RequestDescription: A configured resource limit has been reached for your organization.Example Response:
Common Causes:
  • Maximum API keys created
  • Maximum webhook targets configured
  • Resource quota exceeded
Resolution: Delete unused resources or contact support to increase limits.
HTTP Status: 400 Bad RequestDescription: The authenticated user has access to multiple clients. You must specify which client to use.Example Response:
Resolution: Include the appropriate client context in your request or select a default client in the dashboard.
HTTP Status: 401 UnauthorizedDescription: Authentication credentials are missing, invalid, or expired.Example Response:
Common Causes:
  • Missing x-api-key header
  • Invalid or revoked API key
  • Expired application token
  • Malformed authentication header
Resolution: Verify your API key is correct and active. Check that the x-api-key header is properly formatted.
HTTP Status: 403 ForbiddenDescription: Your credentials are valid but you do not have permission to perform this action.Example Response:
Common Causes:
  • Accessing a resource belonging to another organization
  • API key lacks required scopes
  • User role insufficient for the operation
  • Resource access restricted by policy
Resolution: Verify you have the necessary permissions. Contact your administrator to request access.
HTTP Status: 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:
When it happens: RD availability is geofenced by US state. A customer is blocked when any of their governing US states — a business’s registered or operating address, or an individual’s residential address — is on Dakota’s restricted list. Restricted states are currently FL, GA, NY, TX, WA, and LA (subject to change). Non-US customers, and customers whose US jurisdiction is not yet resolved, are unaffected.Resolution: Use a non-RD destination stablecoin (e.g. USDC) for affected customers, or contact Dakota if you believe the customer’s state has been resolved incorrectly.
HTTP Status: 404 Not FoundDescription: The requested resource does not exist or has been deleted.Example Response:
Common Causes:
  • Resource was deleted
  • Incorrect resource ID
  • Resource belongs to a different organization
  • Typo in the resource path
Resolution: Verify the resource ID is correct. Use list endpoints to confirm the resource exists.
HTTP Status: 409 ConflictDescription: The request conflicts with the current state of the resource.Example Response:
Common Causes:
  • Duplicate external_id when creating a customer
  • Duplicate name for a unique resource
  • Attempting to transition to an invalid state
  • Concurrent modification conflict
Resolution: Use unique identifiers or fetch the existing resource to update it instead.
HTTP Status: 413 Payload Too LargeDescription: The request payload exceeds the maximum allowed size.Example Response:
Common Causes:
  • File upload exceeds 500 MB limit
  • Request body too large
  • Bulk operation with too many items
Resolution: Reduce the payload size or split into multiple requests.
HTTP Status: 422 Unprocessable EntityDescription: The request cannot be completed due to compliance restrictions.Example Response:
Common Causes:
  • Destination wallet address flagged by compliance screening
  • Transaction blocked by sanctions screening
  • Customer flagged for compliance review
  • Geographic restrictions
Resolution: Contact support for details on the compliance block. Do not attempt to circumvent compliance controls.
HTTP Status: 429 Too Many RequestsDescription: You have exceeded the rate limit for API requests.Example Response:
Rate Limit Headers:Every response includes rate limit information:Rate Limits by Authentication Type:Resolution: Implement exponential backoff and respect the Retry-After header.

Cards Errors

Cards is available in sandbox only. See Cards.
HTTP Status: 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.
HTTP Status: 403 ForbiddenDescription: The customer’s Cards capability is not available, for a reason beyond the terms. errors lists what is outstanding. With no errors, the customer’s setup is still completing.Resolution: Read the customer’s capabilities. Retry later if errors is empty, and contact Dakota if it persists.
HTTP Status: 403 ForbiddenDescription: Your account is not activated to issue cards to this type of customer (business or individual).Resolution: Contact Dakota.
HTTP Status: 422 Unprocessable EntityDescription: Cards for individual customers are not available in this environment.Resolution: Contact Dakota.
HTTP Status: 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.
HTTP Status: 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.
HTTP Status: 409 ConflictDescription: Dakota has no usable record to create this cardholder from. Changing the request will not help.Resolution: Contact Dakota.
HTTP Status: 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.
HTTP Status: 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.
HTTP Status: 403 ForbiddenDescription: The cardholder is suspended, so its cards cannot be unfrozen. Freezing and closing still work.Resolution: Only Dakota can lift a suspension.
HTTP Status: 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.
HTTP Status: 501 Not ImplementedDescription: Answering review requests is not available yet.Resolution: None needed until the review process is switched on.
HTTP Status: 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.
HTTP Status: 422 Unprocessable EntityDescription: Cards work with EVM wallets only.Resolution: Use an EVM wallet.
HTTP Status: 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.
HTTP Status: 409 ConflictDescription: The request disagrees with the enablement already recorded for this wallet.Resolution: See Retrying a failed attempt.
HTTP Status: 403 ForbiddenDescription: The card is closed. Closing is permanent, and a closed card cannot be changed.Resolution: Issue a new card.
HTTP Status: 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.
HTTP Status: 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.
HTTP Status: 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.
HTTP Status: 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)

HTTP Status: 500 Internal Server ErrorDescription: An unexpected error occurred on the server. The error details are sanitized for security.Example Response:
Resolution: Retry with exponential backoff. If the error persists, contact support with the request_id.
HTTP Status: 501 Not ImplementedDescription: The requested endpoint or feature is not yet implemented.Example Response:
Resolution: Check the API documentation for available endpoints. Contact support if you believe this is an error.
HTTP Status: 502 Bad GatewayDescription: An upstream provider returned an error.Example Response:
Resolution: Retry with exponential backoff. These errors are typically transient.
HTTP Status: 503 Service UnavailableDescription: The service is temporarily unavailable, typically during maintenance.Example Response:
Resolution: Retry with exponential backoff. Check our status page for maintenance announcements.

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

For POST, PUT, and PATCH requests, always include the x-idempotency-key header to safely retry failed requests. The key must be a valid UUID:
The key is cached for 24 hours. A reused key inside that window returns the original response, so no duplicate operation is created. Only successful responses (status below 400) are cached, so a failed request stays retryable under the same key.
Important: The idempotency key must be unique per logical operation. Reusing a key with a different request body returns the cached response from the original request, not a new operation.

Troubleshooting

Getting Help

When contacting support about an error:
  1. Always include the request_id from the error response
  2. Provide the full error response body
  3. Include the request method, path, and relevant headers (redact the API key)
  4. Describe what you expected vs. what happened

Common Issues

Symptoms: All requests return authentication errors.Checklist:
  1. Verify the x-api-key header is included (not X-Api-Key or api-key)
  2. Check that the API key is not expired or revoked
  3. Ensure there are no extra spaces or newlines in the key
  4. Verify you’re using the correct environment (sandbox vs production)
Symptoms: Getting validation errors without clear field information.Checklist:
  1. Check the errors array in the response for field-level details
  2. Verify your Content-Type header is application/json
  3. Ensure the request body is valid JSON
  4. Compare your request against the OpenAPI specification
Symptoms: Hitting rate limits during normal operation.Checklist:
  1. Check X-RateLimit-Remaining header to monitor usage
  2. Implement request batching where possible
  3. Add caching for frequently accessed resources
  4. Consider using webhooks instead of polling
For detailed troubleshooting, see our Troubleshooting Guide.