Error response format
All errors follow a consistent JSON structure:{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description."
}
}
HTTP status codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created |
202 | Accepted (async job queued) |
204 | No Content (resource deleted) |
400 | Bad Request — invalid parameters |
401 | Unauthorized — missing or invalid API key |
402 | Payment Required — insufficient credits |
403 | Forbidden — valid key but insufficient scope |
404 | Not Found — resource does not exist |
409 | Conflict — duplicate request (idempotency) |
422 | Unprocessable Entity - validation error, or a connected platform or provider refused the request (error.message carries its reason) |
429 | Too Many Requests — rate limited |
500 | Internal Server Error |
502 | Bad Gateway - a connected platform could not be reached at all. Sent without a JSON body. Retry after a short delay. |
Common error codes
| Code | Description |
|---|---|
UNAUTHORIZED | API key is missing or invalid |
FORBIDDEN | Key lacks the required scope |
NOT_YOUR_POST | The post exists and this key can see it, but only its author, the workspace owner or an admin may change it (update, delete, unpublish, edit). error.fix says what to do. A key acts as the person who created it. |
CONNECTION_SCOPE_MISSING | The connected social account is missing a permission this call needs, usually because it was connected before SmartlyQ requested that permission. Reconnect the account to fix it; details.reconnect_required is true. |
INSUFFICIENT_CREDITS | Wallet balance too low |
SUBSCRIPTION_REQUIRED | HTTP 403, retryable: false. The account behind the key has no active subscription, so every key, app connection (MCP, Zapier, Make, Pabbly) and webhook of its workspaces is stopped. Checked before rate limiting and billing: a refused call costs nothing, and the API wallet balance is kept for when the subscription is renewed. details.subscription_state says why: ended (“This account’s subscription has been cancelled. Resume your subscription to use the API.”), none (“This account has no active subscription. Choose a plan to use the API.”) or agency_inactive (“This workspace is not active. Contact your agency to use the API.”, a workspace managed by an agency whose own subscription is over). A subscription cancelled for the end of its billing period keeps working until that day. An unpaid renewal answers 423 BILLING_PAUSED instead. |
RATE_LIMIT_EXCEEDED | You exceeded your own request limit. See rate limiting. |
PLATFORM_RATE_LIMITED | A connected platform is temporarily limiting publishing for that account. Retryable: back off and retry after the cooldown. |
LIMIT_REACHED | You have reached a limit on your account, such as the 200 sub-account cap. Delete what you no longer need, or email [email protected] to have it raised. |
CONTENT_POLICY_VIOLATION | The post breaches the Content Policy and was not created. Not retryable: edit the content, or contact support if you believe the decision is wrong. |
VALIDATION_ERROR | Request body failed validation |
RESOURCE_NOT_FOUND | The requested resource does not exist |
IDEMPOTENCY_CONFLICT | A request with this idempotency key was already processed |
MODEL_NOT_AVAILABLE | The requested AI model is not available on your plan |
JOB_FAILED | An async job encountered an error |
POST_TYPE_UNSUPPORTED | platform_options.<platform>.type names a post format this platform cannot publish. The message lists the accepted values; see Platform options. |
PLATFORM_DAILY_LIMIT_REACHED | HTTP 422, not retryable. The platform’s daily limit for this post type is used up for a selected account - today, Facebook’s 30 Reels per Page in a moving 24-hour window. Nothing is created. Publish after details.next_available_at, or send the post as a different type. details also carries account_id, limit and used. |
PLATFORM_ERROR | HTTP 422. The connected platform refused the request, for example an expired token or a value it does not accept. error.message includes the platform’s own reason. Fix the request or reconnect the account; retrying the same request will fail the same way. |
PLATFORM_UPSTREAM_ERROR | HTTP 422 from the WhatsApp endpoints: WhatsApp refused the request, with its reason in error.message. HTTP 502 only when WhatsApp could not be reached. |
PROVIDER_ERROR | HTTP 422. An AI or media provider could not produce a result. When retryable is true, the same request can succeed on a second try. |
Idempotency
For POST requests, include anX-Idempotency-Key header to prevent duplicate operations:
curl -X POST https://api.smartlyq.com/v1/articles/generate \
-H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
-H "X-Idempotency-Key: unique-request-id-123" \
-H "Content-Type: application/json" \
-d '{ "topic": "My Article", "language": "en" }'

