Limits and errors

This page collects every limit and error you can run into: how fast you can call InfluTo, what each SDK throws, what each status code means, and the format rules for codes and app slugs. For the endpoints themselves, see the HTTP API; for the methods, the SDK reference.

Rate limits

• If you get a 429, back off and retry; a script calling in a tight loop is the usual cause.
• identify is de-duplicated on the server: the same SDK key and user ID within 60 seconds is answered without doing the work again ("deduplicated": true). Call it once per launch, never from a render loop.
• The RevenueCat webhook and the agent REST API have no per-request limit; the agent API has invite limits instead.

Request size

• Every request body is limited to 20 MB; larger requests get 413.
• Asset uploads in the dashboard (Assets) are limited to 20 MB per file.

What throws and what fails soft

Only initialize and reportPurchase throw on network and server errors. The rest return a safe value, so a slow or failed request never crashes your app.

SDK error types

notConfigured covers every 400 from /sdk/purchase: the platform isn't switched to store-direct yet, or the proof is missing or failed verification. A 503 means the exchange rate wasn't available; retry later.

try {
  await InfluTo.reportPurchase({ platform: 'android', purchaseToken });
} catch (e) {
  if (String(e).includes('failed: 503')) scheduleRetry();
}

do {
    _ = try await InfluTo.reportPurchase(jws: jws)
} catch InfluToError.retryable(let status) {
    scheduleRetry(after: status)
} catch {
    print("InfluTo:", error)
}

try {
    InfluTo.reportPurchase(purchaseToken = purchase.purchaseToken)
} catch (e: InfluToError.Server) {
    if (e.retryable) scheduleRetry()
}

try {
  await InfluTo.instance.reportPurchase(platform: 'android', purchaseToken: token);
} on InfluToException catch (e) {
  if (e.retryable) scheduleRetry();
}

import InfluTo, { InfluToApiError } from '@influto/web';

try {
  await InfluTo.reportPurchase({ platform: 'android', purchaseToken });
} catch (e) {
  if (e instanceof InfluToApiError && e.status === 503) scheduleRetry();
}

Code validation errors

validateCode and applyCode return these in error_code (React Native, web) or errorCode (iOS, Flutter as a string; Android as the CodeErrorCode enum, which adds UNKNOWN).

/sdk/set-referral-code can also answer MISSING_USER_ID for a free-access code sent without a user ID. The SDKs' SetCodeResult doesn't expose the code; you get success: false and the message "Could not identify your account. Please try again."

HTTP status codes for /api/sdk/*

The store-direct 400 is intentional: until you switch the platform to store-direct, and that switch needs a green credential check, the endpoint rejects reports. So it's safe to ship the SDK first.

RevenueCat webhook responses

A low wallet balance is not a webhook error: the conversion is still recorded. See RevenueCat and inbound webhooks.

Agent API and MCP

The agent REST API (/api/agent/*) and the MCP tools answer with these statuses; an MCP tool error's text starts with the status.

Details: MCP tools, scopes and REST API.

Code format

Creator referral codes (the code in influ.to/{app_slug}/{CODE}):

• 4–20 characters: A–Z, 0–9, _ and -. Stored uppercase.
• Not one of ADMIN, TEST, API, SYSTEM, NULL, ROOT, DELETE, REMOVE.
• Can't start with INFLU-, which is reserved for creator access codes InfluTo issues itself.

Free-access codes you create on Free Access Codes: the same characters and length, uppercase, unique across InfluTo, and also never starting with INFLU-.

When a user types a code, the SDK trims and uppercases it. The server then ignores spaces and any other character outside the alphabet when it looks the code up, and checks creator codes before free-access codes. The SDK stores and sends to RevenueCat the code it was given, so clean the input in your field — see building your own field.

App slug

The slug is the first part of your referral links, influ.to/{app_slug}/{CODE}.

• 3–20 characters: lowercase letters, digits and - (the dashboard enforces this as you type).
• Unique across InfluTo, and not one of the names the site itself uses (such as api, dashboard or a language code). My Apps → Add App checks availability as you type.