paperclipai/paperclip · warning · PhotonError

quota

quota

Error message

Photon Cloud request limit reached; retry later

What it means

Thrown by PhotonCloudClient.request when Photon Cloud responds with HTTP 429, meaning the project has exhausted its request quota / rate limit. The code raises PhotonError 'quota' advising the caller to retry later.

Solutions

1. Back off and retry later with exponential backoff and jitter
2. Cache allocation/token results and only renew near expiry (the runtime renews at expiresIn*0.8) instead of calling allocation repeatedly
3. Consolidate multiple instances onto fewer allocation calls or a shared token cache
4. Upgrade the Photon project plan or request a quota increase if 429s are routine

Example fix

// before: tight retry loop
while (!ok) { ok = await tryAllocate(cloud, id, secret); }
// after: honor backoff
const delay = Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 1000;
await new Promise(r => setTimeout(r, delay));
ok = await tryAllocate(cloud, id, secret);

// client-side token-budget rate limiter
let lastCall = 0;
async function throttledAllocate(cloud, id, secret, minIntervalMs = 60_000) {
  const wait = lastCall + minIntervalMs - Date.now();
  if (wait > 0) await new Promise(r => setTimeout(r, wait));
  lastCall = Date.now();
  return cloud.allocation(id, secret);
}

null

try {
  return await cloud.allocation(projectId, secret);
} catch (e) {
  if (e instanceof PhotonError && e.code === "quota")
    return retryWithBackoff(() => cloud.allocation(projectId, secret), { attempts: 5, baseMs: 30_000, maxMs: 600_000 });
  throw e;
}

When it happens

Trigger: Calling allocation(), inspect(), or the token-minting request (imessage/tokens POST) too frequently for the project's plan; token renewal loops with tight retry intervals; many lines/allocation checks fanning out under one project.

Common situations: A retry loop hammering Photon Cloud after earlier network errors; scheduled reconnection storms across many instances sharing one project; free-tier limits exceeded during heavy testing.

Related errors

• dropping batch after attempt(s); event(s) lost
• paperclip_runner_chat_attachment_read_limit
• railway_rate_limited
• Too many active setup-token login sessions.
• Anthropic Managed Agents request failed with HTTP

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/18f25ae38aaa9dc6. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/photon/cloud.ts:147

          headers: {
            authorization: `Basic ${Buffer.from(`${projectId}:${projectSecret}`).toString("base64")}`,
            accept: "application/json",
          },
        },
      );
    } catch {
      throw new PhotonError(
        "network",
        "Photon Cloud could not be reached; retry the connection",
      );
    }
    if (response.status === 401 || response.status === 403)
      throw new PhotonError(
        "credentials",
        "Photon rejected this project ID or secret",
      );
    if (response.status === 429)
      throw new PhotonError(
        "quota",
        "Photon Cloud request limit reached; retry later",
      );
    if (!response.ok)
      throw new PhotonError(
        "network",
        `Photon Cloud returned HTTP ${response.status}`,
      );
    const reader = response.body?.getReader();
    if (!reader)
      throw new PhotonError(
        "invalid_response",
        "Photon returned an empty response",
      );
    const chunks: Uint8Array[] = [];
    let length = 0;
    try {
      for (;;) {

View on GitHub (pinned to 3f1d897a7c)