Error Handling

HTTP Status Codes

Status	Meaning	When It Occurs
`200`	Request processed	Simulation or validation completed. Check `result.status` for simulation success/failure.
`400`	Bad request	Invalid parameters, missing required fields, or malformed request body.
`401`	Unauthorized	Missing or invalid API key.
`404`	Not found	Simulation ID not found or expired (validate endpoint only).
`429`	Rate limited	Too many requests. Back off and retry.
`500`	Internal error	Server-side failure. Retry after a short delay.

Simulation Errors

A 200 response from /simulate does not always mean the transaction would succeed on-chain. Check result.status:

const simulation = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
  method: "POST",
  headers: { "Authorization": `Bearer ${ENSO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify(request),
}).then((res) => res.json());

if (simulation.result.status === "Success") {
  console.log("Predicted output:", simulation.result.amountOut);
  console.log("Gas estimate:", simulation.result.gas);
} else {
  console.error("Transaction would fail:", simulation.result.error);
}

Common Simulation Failures

Error Type	Description	How to Fix
`CallFailed`	The transaction call failed during simulation	Check that the sender has sufficient balance and the calldata is correct
`CallReverted`	The contract reverted the transaction	Inspect the revert reason — often an insufficient allowance or failed require check
`DecodeError`	Could not decode the transaction result	Verify the `data` field contains valid calldata for the target contract
`ProviderError`	RPC provider error during simulation	Retry — this is usually transient

Validation Errors

Simulation Not Found (404)

If the simulation has expired (after 5 minutes) or the ID is invalid:

{
  "statusCode": 404,
  "message": "Simulation a1b2c3d4-e5f6-7890-abcd-ef1234567890 not found or expired"
}

Fix: Re-simulate to get a fresh simulationId.

Partial Check Failures

When valid is false, inspect the checks object to find which fields failed:

const validation = await validate(simulationId, transaction);

if (!validation.valid) {
  const failures = Object.entries(validation.checks)
    .filter(([, passed]) => !passed)
    .map(([field]) => field);

  console.error("Failed checks:", failures);
  // Re-simulate instead of retrying validation
}

Rate Limiting

Quoter enforces rate limits per API key. When you receive a 429 response, back off before retrying:

async function simulateWithRetry(request: SimulateRequest, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch("https://quoter.api.enso.build/api/v1/simulate", {
      method: "POST",
      headers: { "Authorization": `Bearer ${ENSO_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify(request),
    });

    if (response.status === 429) {
      await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
      continue;
    }

    return await response.json();
  }

  throw new Error("Rate limited after max retries");
}

Updated

Quoter

Guides

Reference

API Reference

HTTP Status Codes

Simulation Errors

Common Simulation Failures

Validation Errors

Simulation Not Found (404)

Partial Check Failures

Rate Limiting

​HTTP Status Codes

​Simulation Errors

​Common Simulation Failures

​Validation Errors

​Simulation Not Found (404)

​Partial Check Failures

​Rate Limiting

HTTP Status Codes

Simulation Errors

Common Simulation Failures

Validation Errors

Simulation Not Found (404)

Partial Check Failures

Rate Limiting