Error Codes

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid token symbol. Must be USDC, ETH, or ADAO."
}

The error field contains a human-readable description of the problem. Some responses may include additional fields for context.

When a workspace accumulates 3 consecutive payout failures, PayDirect activates the circuit breaker and pauses all payouts for that workspace. Error responses include a structured code field:

// Handling circuit breaker in your agent
const res = await fetch(url + "/api/v1/payouts", { method: "POST", ... });
const data = await res.json();

if (data.code === "CIRCUIT_BREAKER_OPEN") {
  // Workspace is paused — stop scheduling payouts
  console.error("Payouts paused:", data.error);
  // Option 1: Wait for auto-resume (30 min)
  // Option 2: Fix the issue, then POST /api/v1/workspaces/{id}/resume
}

if (data.failStreak > 0) {
  console.warn(`Fail streak: ${data.failStreak}, remaining: ${data.remainingBeforePause}`);
}

See Payouts API > Circuit Breaker for the full resume flow and agent integration guide.

When the rate limit is exceeded, the response includes headers to help you retry appropriately:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708100182
Retry-After: 42

{
  "error": "Rate limit exceeded"
}

// Recommended retry logic
if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get("retry-after") || "5");
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry the request
}