Skip to main content

​
Error Response Format

All errors return a JSON body: 
{
  "error": "Memory key already exists. Use PUT /v1/memory/:id to create a new version.",
  "existingId": "abc-123"
}

​
Common Error Codes

StatusErrorSolution
400Invalid parametersCheck required fields, valid expiresIn format (max 365d)
401UnauthorizedVerify your API key is correct — may have been rotated
402Insufficient creditsTop up credits via /v1/billing/initiate-topup or the dashboard
403Agent suspended or revokedContact the account administrator
404Memory not foundCheck the memory ID exists and belongs to your agent
409Memory key already existsUse PUT /v1/memory/:id to update, or choose a different key
413File too largeMax blob size is 10 MB
413Storage quota exceededDelete unused memories or request a quota increase
415Unsupported Content-TypeSend application/json or multipart/form-data for POST/PUT/PATCH
422Credential detected in shared contentSet visibility: "private" for content with secrets
422Invalid payment amountPayment gateway returned an invalid amount — contact support
429Rate limitedWait and retry with exponential backoff. Global: 300/min per key. Writes: 30/min per agent
429Too many rotation attemptsKey rotation is limited to 3 per 15 minutes
502Shelby storage errorRetry up to 3× with 2–4s delays

​
Retry Strategy

For 429 and 5xx errors, implement exponential backoff: 
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 || err.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw err;
    }
  }
}

​
Validation Errors

With Zod schema validation, 400 errors include structured field-level details: 
{
  "error": "Validation failed",
  "details": [
    { "field": "type", "message": "Must be a built-in type or custom:..." },
    { "field": "content", "message": "Required" }
  ]
}
Other 400 errors still use the simple format: 
{
  "error": "Invalid expiresIn format. Use e.g. \"1h\", \"24h\", \"30d\". Minimum 10 seconds."
}