Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dfns.co/llms.txt

Use this file to discover all available pages before exploring further.

Below is the error structure returned by Dfns API.
FieldDescriptionType
idThe error ID. You can share this with Dfns support to help troubleshoot your issue.String
statusHTTP status code.Integer
messageThe error message.String
detailsStructured 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 our 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 our 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 our 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.
Last modified on May 15, 2026