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"
}The request body or query parameters failed validation. Check the error message for the specific field that failed.
Missing or invalid authentication credentials. Ensure your API key or JWT token is valid and not expired.
The authenticated identity does not have permission to perform this action on the target resource.
The requested resource does not exist. Verify the object ID, template ID, or endpoint path.
The request conflicts with the current state of the resource — for example, attempting a state transition that violates the lifecycle rules.
You have exceeded the rate limit for this endpoint group. Check the Retry-After header for the reset timestamp.
An unexpected error occurred on the DUAL platform. If this persists, contact support with the x-request-id header value.
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
}
}