{ "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 | 409 | Scheduling content with no rendered slide images |
missing_privacy_level | 400 | mode: "publish" without privacyLevel |
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 / tiktok_publish_failed | 502 | TikTok itself rejected the request |
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.
}
}