Below is the error structure returned by Dfns API.
| Field | Description | Type |
|---|
id | The error ID. You can share this with Dfns support to help troubleshoot your issue. | String |
status | HTTP status code. | Integer |
message | The error message. | String |
details | Structured data that provides additional error context. | Object |
Example
{
"error": {
"id": "2038837570328299032",
"status": 404,
"message": "wallet not found",
"details": {
"walletId": "wa-1f04s-lqc9q-xxxxxxxxxxxxxxxx",
"orgId": "or-195qp-opddr-xxxxxxxxxxxxxxxx"
}
}
}
Common errors
400 Bad Request
The request body or parameters are invalid.
Common causes:
- Missing required fields
- Invalid field values or types (e.g., wrong address format, unsupported network)
- Malformed JSON body
Check the message and details fields for specifics on which parameter failed validation.
401 Unauthorized
Your Authorization header is missing, malformed, or the token is invalid/expired.
Solutions:
- Verify the token is included as
Authorization: Bearer <token>
- Check the token hasn’t expired — decode it at jwt.io and check the
exp field
- Ensure you’re using the correct region (
api.dfns.io vs api.uae.dfns.io)
402 Payment Required
The requested feature is not available on your current plan.
Solutions:
- Contact your account manager or support to upgrade your plan
403 Forbidden
You’re calling a state-changing endpoint (POST, PUT, DELETE) without the required X-DFNS-USERACTION header, or the user lacks permission.
Solutions:
GET requests don’t require the X-DFNS-USERACTION header. If you’re getting this error on a GET request, check your permissions.
404 Not Found
The requested resource doesn’t exist.
Common causes:
- Incorrect wallet, user, or policy ID
- Resource was deleted
- Resource belongs to a different organization
409 Conflict
A resource with the same unique constraint already exists.
Common causes:
- Reusing an
externalId with a different request body or wallet — see idempotency
- Assigning a permission that is already assigned to the user
Solutions:
- For idempotency conflicts: use a unique
externalId for each distinct request. Retrying the exact same request (same body, same wallet) with the same externalId returns the original response with status 200.
- Check the
details field in the error response to identify the existing entity
410 Gone
The resource was permanently deleted and can no longer be accessed.
412 Precondition Failed
A business logic precondition was not met. For example, the resource is in a state that doesn’t allow the requested operation.
422 Unprocessable Content
The request is well-formed but cannot be processed because the target resource is in an invalid state (e.g., archived or deactivated).
429 Too Many Requests
You’ve exceeded the API rate limits.
Solutions:
- Implement exponential backoff and retry logic
- Reduce the frequency of API calls
- Contact Dfns support if you need higher limits
500 Internal Server Error
An unexpected error occurred on the server.
Solutions:
- Retry the request after a short delay
- If the error persists, contact support with the error
id from the response
Policy pending (202)
Not an error — this response means your request was accepted but a policy requires approval before it can be completed. The Dfns SDKs surface this as a PolicyPendingError.
Check the approval process for how to approve pending requests. 