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
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)
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
You’re reusing an externalId with a different request body or wallet. This error is specific to idempotency.
Solutions:
- Use a unique
externalId for each distinct request
- If retrying the exact same request (same body, same wallet), reusing the
externalId will return the original response with status 200
- Check the
details.duplicate field in the error response to find the existing entity
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
