Troubleshooting

• Ensure you're using the full key (not just the kb_abc prefix shown in the dashboard)
• Check that the header format is exactly Authorization: Bearer kb_...
• Verify the key hasn't been revoked in Dashboard → API Keys
• Note: consumer endpoints (/r/:token) don't need authentication. If you're passing a key to a claim URL, remove it

You've exceeded your plan's per-key rate limit. To resolve this:

• Add exponential backoff and retry logic to your client
• Both the TypeScript and Python SDKs have built-in retries (default: 2 retries, so 3 attempts total)
• Spread requests across multiple API keys if needed
• Consider upgrading your plan for higher rate limits

This means you've hit either your daily creation quota or active kubbi limit for your current plan. Options:

• Wait for existing kubbis to expire or be claimed (burn-after-read)
• Manually delete kubbis you no longer need
• Use shorter TTLs so kubbis expire faster
• Upgrade your plan for higher quotas

The kubbi is no longer available. This happens when:

• The TTL has elapsed (status: expired)
• All allowed retrievals were used (status: burned)
• The producer deleted it (status: deleted)

In all cases, the encrypted content has been permanently overwritten and cannot be recovered. Use GET /r/:token/inspect to check status before claiming.

Common causes for package validation failures:

• More files than your plan allows in the files array
• Total decoded size exceeds your plan's package size limit
• Duplicate filenames (case-insensitive, so README.md and readme.md conflict)
• Invalid filename characters (only a-zA-Z0-9._-, must start with alphanumeric)
• Including both content and files in the same request (mutually exclusive)
• Invalid base64 encoding for binary files

• Check your internet connection and any proxy/firewall settings
• Verify you're connecting to https://api.kubbi.ai (HTTPS required in production)
• If using a custom baseUrl, ensure it's correct
• Check the timeoutMs / timeout setting. Default is 30 seconds
• The SDK retries failed requests up to 2 times by default (3 attempts total). If all retries fail, there may be a persistent connectivity issue

A few things to check:

• Inspect does not count as a retrieval, but claim does. If maxRetrievals was 1, the first claim burns the kubbi
• For application/json content, the claim response returns parsed JSON (not a string)
• For packages, binary files are returned with encoding: "base64". Decode them on the client side
• Use the SDK's type guards (isPackageClaim for claim responses, isPackageInspect for inspect responses) to correctly handle both single and package shapes