Error Response Format
All errors return a JSON response with theapplication/problem+json content type:
Response Fields
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
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
invalid-identifier
invalid-identifier
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: Resolution: Include the appropriate client context in your request or select a default client in the dashboard.
400 Bad RequestDescription: The authenticated user has access to multiple clients. You must specify which client to use.Example Response:authentication-error
authentication-error
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: 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.
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
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: Common Causes:
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
HTTP Status: Rate Limit Headers:Every response includes rate limit information:
429 Too Many RequestsDescription: You have exceeded the rate limit for API requests.Example Response:Rate Limits by Authentication Type:
Resolution: Implement exponential backoff and respect the
Retry-After header.Server Errors (5xx)
internal-error
internal-error
HTTP Status: Resolution: Retry with exponential backoff. If the error persists, contact support with the
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
HTTP Status: Resolution: Check the API documentation for available endpoints. Contact support if you believe this is an error.
501 Not ImplementedDescription: The requested endpoint or feature is not yet implemented.Example Response:provider-error
provider-error
HTTP Status: Resolution: Retry with exponential backoff. These errors are typically transient.
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
For POST requests, always include thex-idempotency-key header to safely retry failed requests:
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
Symptoms: Getting validation errors without clear field information.Checklist:
- 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
Symptoms: Hitting rate limits during normal operation.Checklist:
- Check
X-RateLimit-Remainingheader to monitor usage - Implement request batching where possible
- Add caching for frequently accessed resources
- Consider using webhooks instead of polling

