Troubleshooting Buffer's API
If something isn't working as expected with Buffer's API, this article covers the most common issues and how to fix them, from authentication errors to media problems and rate limits. It also points you to where to get help if you're stuck.
📝 Setting up for the first time? See How to create your Buffer API key and Connecting Buffer to automation tools and AI assistants.
In this article:
- Common errors and edge cases
- Authentication issues
- Hosting media for use with the API
- Understanding your API usage and rate limits
- How to get help
- FAQ
Common errors and edge cases
| Issue | What to check |
| Can't generate an API key, or the option isn't appearing | Make sure your Buffer account email is verified. Head to Settings → Account and look for a verification prompt, or check your inbox for a verification email from Buffer. |
| Post not appearing in Buffer | Is your API key correct? Is your workflow turned on? |
| Posted to the wrong channel | Is the correct channel selected in your setup? |
| AI says it posted but nothing shows | API access may have expired, or the key's permissions may be too limited. Check the key's expiration and permissions in API settings. |
| Duplicate posts | Your workflow likely triggered more than once. |
| Video not attaching, or a media URL error | The media URL must be publicly accessible and stay reachable until the post publishes. See Hosting media below. |
| Post rejected when it includes both a link preview and media | You can't send a link attachment and a media file in the same post. Pick one. Previously the media was silently dropped, which produced empty video posts. Now you'll get a clear error instead. |
| Hitting API usage limits unexpectedly | Check the usage breakdown by app client in your API settings to see which integration is consuming the most capacity. |
| Claude MCP integration not working | Make sure Node.js version 18 or higher is installed. If you have multiple versions, confirm Claude Desktop is using 18+. |
Authentication issues
Most authentication errors come down to the API key itself or how it's being sent.
- Check your key is correct and current. If it's expired, regenerate it and update it everywhere it's used. See How to create your Buffer API key.
- Check the key's permissions. Each key carries a specific set of permissions, which you can see in the collapsible Permissions row next to the key in Settings → API. If a key was created without posting permission, it can read data but won't be able to create posts.
- Confirm your Buffer permissions allow posting. Posts created via the API respect your channel access role. If you're set to Requires Approval, posts are saved as drafts awaiting approval.
- Make sure the
Bearerprefix is included in your authorization header. For example:
{ "mcpServers": { "buffer": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.buffer.com/mcp", "--header", "Authorization: Bearer API_KEY" ] } } }
The Bearer prefix before your key is required.
📝 Note: If your AI assistant reports success but nothing appears in Buffer, your access may have expired or your permissions may be too limited. Look for error messages in your tool's activity or logs.
Hosting media for use with the API
When you include an image or video in a post via the API, Buffer doesn't accept direct file uploads. Instead, the media needs to be hosted online and shared as a public URL, a link anyone (or any tool) can open without logging in.
⚠️ Important: Google Drive links don't work for this. Drive links require the viewer to be signed in, so Buffer's API can't retrieve the file. The same applies to Dropbox share links, any storage service that restricts access by default, or any URL that returns Cross-Origin Resource Policy (CORP) headers or requires authentication.
⚠️ Your media link needs to stay reachable until the post publishes, not just when you create it. Buffer fetches the file at the moment the post goes out, which for scheduled or queued posts can be hours or days later. Avoid links that expire, including signed delivery URLs from Cloudinary or pre-signed S3 links. They often work when you set the post up and then fail silently before it publishes. Use a stable, permanent URL.
Recommended media hosting options
Cloudinary is a media management platform with a generous free tier. After you upload an image or video, you get a direct, publicly accessible URL. It also has optional resizing and transformation features, handy for meeting each network's media requirements. Use a plain delivery URL rather than a signed one, so the link doesn't expire.
Cloudflare R2 is an object storage service with a free tier. A good fit if you already use Cloudflare or are comfortable with a slightly more technical setup. Once a file is uploaded and the bucket is public, the resulting URL works reliably with Buffer's API.
How to check if a URL will work
Before plugging a media URL into your workflow, open it in an incognito or private browser window. If the file loads without asking you to sign in, it'll work with the API. If it prompts for a login or shows an error, adjust the sharing settings or switch hosting options.
💡 Tip: Once you've confirmed a URL works in incognito, save it somewhere handy. The same link can be reused across multiple posts or workflows as long as the file stays in place.
Understanding your API usage and rate limits
Your API Settings shows your API usage broken down by client, so you can see how much of your rate limit each key or integration is using.
- Personal API keys. Usage for all your personal keys is shown together in one group and shares a single pool.
- App clients. Each app client (third-party integration or custom app) shows its own usage separately.
How rate limits work
Rate limits apply per client. Each personal API key group and each app client has its own limit, based on the plan of the organization where the client was created. Each client has three rolling windows:
| Window | Free | Essentials | Team |
| Per 15 minutes | 100 | 100 | 100 |
| Per 24 hours | 250 | 250 | 500 |
| Per 30 days | 3,000 | 7,500 | 15,000 |
The per-30-days figures match the request limits in the plan comparison in What is Buffer’s API?
All windows are rolling. They slide forward continuously from your most recent requests, rather than resetting on a clock boundary.
If a client exceeds any limit, further requests return a 429 error until the window resets. If you use the Buffer CLI, it warns you automatically when you're running low, and tells you how long to wait if you hit the cap.
📝 Note: Usage is shared across all your personal API keys as a group. App clients each have their own separate limits. View current usage and limits per client in your Developer Dashboard.
How to get help
If you've worked through the fixes above and are still stuck:
- Check the developer docs. For implementation details, code examples, and the full API reference, see our developer documentation.
- Join the developer community. Our developer Discord is a good place to ask questions and compare notes with others building on Buffer's API.
- Email our team. Reach out at hello@buffer.com and we'll help point you in the right direction. For developer-specific questions, you can also contact developersupport@buffer.com.
FAQ
Why am I getting a 429 error?
A 429 means you've exceeded one of your rate-limit windows (per 15 minutes, per 24 hours, or per 30 days). Requests resume once the window rolls forward. Check your usage by client in your API settings to see which integration is using the most capacity.
My media URL won't attach. What's wrong?
The URL most likely isn't publicly accessible, or it stopped working before the post published. Open it in an incognito window: if it asks you to sign in or shows an error, Buffer's API can't retrieve it. Google Drive links and other access-restricted storage won't work, and neither will links that expire. Use a stable public URL from a host like Cloudinary or Cloudflare R2.
My AI assistant says it posted, but I don't see anything.
Your API access may have expired, or the key's permissions may be too limited. Recheck your key, expand its Permissions row in your API settings to confirm it's allowed to create posts, confirm your Buffer channel permissions allow posting, and look for error messages in your tool's logs.
Why can't I create an API key at all?
The most common reason is an unverified email. Head to Settings → Account and verify your email, then try again. Note that only organization owners can currently create keys.
📝 Need help with the API? Send us an email at hello@buffer.com and our Advocacy team will be standing by to assist!