{ "error": { "code": "not_found", "message": "Content not found.", "requestId": "req_msurf4pt1" } }
requestId is unique per request — include it when reporting an issue.
| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing/malformed Authorization header, or an invalid key |
key_revoked | 401 | The API key was revoked |
key_expired | 401 | The API key passed its expiresAt |
missing_scope | 403 | The key lacks a required scope |
not_found | 404 | Resource doesn’t exist or isn’t owned by this account |
invalid_request | 400 | Missing or malformed required fields |
missing_idempotency_key | 400 | A credit-spending POST without Idempotency-Key |
not_approved | 409 | Scheduling content that isn’t approvalStatus: "approved" |
not_ready | 409 | Approving/rejecting content that isn’t status: "ready" |
no_images / not_postable | 409 | Scheduling content with no finished slide images the API can post |
slide_missing / unsupported_image_format / image_too_large / too_many_slides | 409 | A slide’s file is gone, isn’t JPEG/WebP, or the deck is too big to post |
account_not_found | 404 | Scheduling to a TikTok account that isn’t on this Stratos account (see GET /v1/accounts) |
account_not_connected / account_needs_reauth | 409 | The TikTok account needs reconnecting in Stratos |
cross_app | 409 | The TikTok account posts for a different app than this content |
already_scheduled | 409 | That content is already waiting to go to that account |
already_sending / already_sent | 409 | Deleting a schedule whose post is already on its way to, or on, TikTok |
missing_privacy_level / invalid_privacy_level | 400 | mode: "publish" without a privacyLevel, or one the account doesn’t allow |
insufficient_credits | 402 | Not enough credits — also carries insufficient: true |
rate_limited | 429 | Too many requests — check the Retry-After header (seconds) before retrying |
tiktok_create_failed | 409 / 502 | The TikTok queue refused the post (409) or couldn’t be reached (502) |
queue_unavailable | 502 | The TikTok queue couldn’t be reached to withdraw a post — nothing was deleted |
not_implemented | 501 | The endpoint exists but its pipeline isn’t wired yet (remix, illustrated/hook_video generation) |
db_error | 502 | The API’s own database call failed |
internal_error | 500 | Unhandled error — report the requestId |
Worked example: handling insufficient credits
insufficient_credits is the one error worth handling specially — it’s an expected outcome, not a bug, and retrying the identical request won’t fix it:
402
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this generation.",
"requestId": "req_msurf4pt1",
"insufficient": true
}
}
const res = await fetch("https://www.try-orbit.com/api/v1/content", { method: "POST", /* ... */ });
if (res.status === 402) {
const { error } = await res.json();
if (error.insufficient) {
// Check GET /v1/credits, surface the gap to a human, or stop —
// never retry a 402 hoping it resolves itself.
}
}