Getting started
Errors & Rate Limits
API error codes, rate limit headers, and how to handle failures.
All successful responses return HTTP 200. All errors return a consistent format:
{
"error": {
"message": "Human-readable error message",
"code": "ERROR_CODE"
}
}Error Reference
| HTTP Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Invalid request body or parameters |
| 401 | INVALID_API_KEY | Missing or invalid API key |
| 402 | INSUFFICIENT_CREDITS | Not enough credits for this operation |
| 402 | MEDIA_REQUIRES_PURCHASE | Image/video generation needs a credit purchase first |
| 403 | FORBIDDEN | You don't have access to this resource |
| 403 | INSUFFICIENT_SCOPE | API key is missing a required permission scope |
| 404 | NOT_FOUND | Resource not found |
| 409 | ALREADY_PUBLISHED | Post has already been published |
| 413 | FILE_TOO_LARGE | Uploaded file exceeds size limit |
| 422 | PLATFORM_NOT_CONNECTED | Social platform not connected for publishing |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |
| 500 | INTERNAL_ERROR | Server error — try again later |
| 502 | CANCEL_FAILED | Couldn't cancel the scheduled publish, try again shortly |
Rate Limits
Rate limits vary by endpoint. When you exceed the limit, you'll receive a 429 response with rate limit headers.
Rate Limit Headers
Every response includes rate limit information:
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1736534460Rate Limit Error
{
"error": {
"message": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 45
}
}Handling Errors
JavaScript Example
async function generateContent(prompt, postTypes) {
const res = await fetch('https://powerpost.ai/api/v1/content/generate', {
method: 'POST',
headers: {
'x-api-key': process.env.POWERPOST_API_KEY,
'X-Workspace-Id': 'YOUR_WORKSPACE_ID',
'Content-Type': 'application/json',
},
body: JSON.stringify({ prompt, post_types: postTypes, research_mode: 'regular' }),
})
if (!res.ok) {
const { error } = await res.json()
switch (error.code) {
case 'INSUFFICIENT_CREDITS':
throw new Error('Please add more credits')
case 'RATE_LIMIT_EXCEEDED':
// Wait and retry
await new Promise((r) => setTimeout(r, error.retryAfter * 1000))
return generateContent(prompt, postTypes)
default:
throw new Error(error.message)
}
}
return res.json()
}Purchase required (image & video)
Image and video generation need a credit purchase first. Signup credits still work for non-media workflows. The 402 body looks like this:
{
"error": {
"message": "Image and video generation requires a credit purchase. Free signup credits cover writing, publishing, analytics, and comments.",
"code": "MEDIA_REQUIRES_PURCHASE",
"action": "buy_credits",
"checkout_path": "/studio/credits"
}
}action is buy_credits. Send the user to checkout_path.
Request Tracing
All responses include an X-Request-Id header:
X-Request-Id: 7f3c9a2b-4d5e-6f7g-8h9i-0j1k2l3m4n5oInclude this ID when contacting support for faster debugging.