Skip to main content

​
HTTP Status Codes

StatusMeaningWhen It Occurs
200Request processedSimulation or validation completed. Check result.status for simulation success/failure.
400Bad requestInvalid parameters, missing required fields, or malformed request body.
401UnauthorizedMissing or invalid API key.
404Not foundSimulation ID not found or expired (validate endpoint only).
429Rate limitedToo many requests. Back off and retry.
500Internal errorServer-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://shield.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 TypeDescriptionHow to Fix
CallFailedThe transaction call failed during simulationCheck that the sender has sufficient balance and the calldata is correct
CallRevertedThe contract reverted the transactionInspect the revert reason — often an insufficient allowance or failed require check
DecodeErrorCould not decode the transaction resultVerify the data field contains valid calldata for the target contract
ProviderErrorRPC provider error during simulationRetry — 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

Shield 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://shield.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