Error Reference

Every Dual API error returns a JSON body with code, message, and an optional details array. The TypeScript and Python SDKs map these to typed exception classes.

Response Shape

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded for write operations",
    "details": [
      { "field": "actions", "reason": "60 req/min limit reached" }
    ]
  },
  "x_request_id": "req_abc123def456"
}

Error Codes

400 Bad Request, DualValidationError

The request body or query parameters failed validation. Check the error message for the specific field that failed.

401 Unauthorized, DualAuthError

Missing or invalid authentication credentials. Ensure your API key or JWT token is valid and not expired.

403 Forbidden, DualAuthError

The authenticated identity does not have permission to perform this action on the target resource.

404 Not Found, DualNotFoundError

The requested resource does not exist. Verify the object ID, template ID, or endpoint path.

409 Conflict, DualConflictError

The request conflicts with the current state of the resource, for example, attempting a state transition that violates the lifecycle rules.

429 Too Many Requests, DualRateLimitError

You have exceeded the rate limit for this endpoint group. Check the Retry-After header for the reset timestamp.

500 Internal Server Error, DualServerError

An unexpected error occurred on the Dual platform. If this persists, contact support with the x-request-id header value.

503 Service Unavailable, DualServerError

The service is temporarily unavailable, usually during a deployment or maintenance window. Retry with exponential backoff.

Handling Errors in the SDK

import { DualClient, DualAuthError, DualNotFoundError, DualRateLimitError } from "dual-sdk";

const client = new DualClient({ token: process.env.DUAL_API_KEY, authMode: "api_key" });

try {
  const obj = await client.objects.get("obj_abc123");
} catch (err) {
  if (err instanceof DualNotFoundError) {
    console.log("Object does not exist:", err.message);
  } else if (err instanceof DualRateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter, "seconds");
  } else if (err instanceof DualAuthError) {
    console.log("Authentication failed:", err.message);
  } else {
    throw err; // unexpected error
  }
}