Idempotency

​

Idempotent routes

​

Replay results

​

1. Cached replay — 200/201/202

​

2. In-progress replay — 409 API_007

{
  "success": false,
  "error": {
    "code": "API_007",
    "message": "Request with this idempotency key is already being processed"
  }
}

​

3. Key conflict — 409 API_008

• Send the original body verbatim.
• Restart the applicable two-stage flow. Do not edit or reuse an old signed authorization for a different operation.

{
  "success": false,
  "error": {
    "code": "API_008",
    "message": "Idempotency key conflict: a previous request with this key used a different body"
  }
}

​

Retry rules

​

Safe to retry

• 5xx responses (API_600, API_506). Wait and retry with the same anchor and body.
• API_007. In-progress replay. Back off and retry.
• Network errors before a response. Wait and retry with the same anchor. If Glider processed the first request, the retry returns the cached result.

​

Do not retry

• API_008. The server has rejected this body. Start over.
• 400-class errors. Fix the input before you retry.
• API_202 (portfolio already exists). Terminal. The user is already enrolled in this strategy.

​

Consult before retrying

• 404. A retry with the same ID returns the same error. Check the tenant and the resource ID.
• 401/403. Fix auth or scope first.

​

Anchor details

​

flowId (enrollment)

• Issued by POST /v2/enroll/signature as an opaque string.
• Valid for 24 hours. After that time, stage 2 returns 400.
• Binds the assigned agent wallet and peeks the user’s next account index.
• Do not create a new flowId to retry stage 2. Use the original flowId unless the error is final.

​

message.nonce (withdrawal)

• A 32-byte 0x-prefixed hex string issued by POST /v2/portfolios/{id}/withdraw/signature.
• Also returned as authorizationId in the response envelope. The two fields have the same value.
• The signed authorization is valid for 10 minutes from issuance. After that, any stage-2 submission, including an otherwise identical replay, returns API_216.
• Glider keeps the retry record for 24 hours. This record does not override the signed expiry.
• The nonce is part of the EIP-712 hash. Thus, the signature binds the nonce to the withdrawal. The nonce is also the replay key for the transfer.

​

Signed payload hash (chain activation)

• Stage 1 is deterministic and does not reserve an idempotency record.
• Stage 2 derives its key from portfolioId, the ordered chainIds, and the owner’s signature.
• Retry with the same chainIds and signature. A different signed payload is a different activation request.
• Completed and in-flight records live for 24 hours.

​

Safe retry example

async function submitWithdrawalWithRetry(
  apiKey: string,
  portfolioId: string,
  message: WithdrawalMessage,
  signature: string,
) {
  const maxAttempts = 5;
  let backoffMs = 1000;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(
      `https://api.glider.fi/v2/portfolios/${portfolioId}/withdraw`,
      {
        method: "POST",
        headers: {
          "x-api-key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ message, signature }),
      },
    );

    if (res.ok) return await res.json();

    const body = await res.json();
    const code = body?.error?.code;

    if (code === "API_007" || res.status >= 500) {
      await new Promise((r) => setTimeout(r, backoffMs));
      backoffMs = Math.min(backoffMs * 2, 30_000);
      continue;
    }

    throw new Error(`Withdrawal failed: ${code} — ${body?.error?.message}`);
  }

  throw new Error("Withdrawal exceeded max retry attempts");
}

​

Routes without an explicit anchor

• POST /v2/strategies creates a new strategy for each call. Your application must prevent duplicates.
• POST /v2/portfolios/{id}/start and /stop are idempotent by state. They do not use an explicit anchor.
• POST /v2/portfolios/{id}/rebalance has a cooldown for each portfolio. A duplicate trigger can return 429 with Retry-After.
• Read routes are safe to retry and do not need an anchor.