Documentation / Errors

Error codes reference

All 50 codes that /api/v1 can emit, grouped by category. Every error response uses the same ErrorResponse envelope with error, code, status, and optional details / retryAfter.

How to use this page

  • Match your error handler on code — never the human error string.
  • Generic codes (AUTH_REQUIRED, AUTH_INVALID_KEY, RATE_LIMITED, VALIDATION_ERROR, INTERNAL_ERROR) can come from any endpoint.
  • On RATE_LIMITED, honor the retryAfter field (seconds) — don't exponential-backoff.

Authentication & permission · 7 codes

Code HTTP Description Recovery
AUTH_REQUIRED 401 No Bearer token and no session cookie. Attach Authorization: Bearer vg_live_...
AUTH_INVALID_KEY 401 Bearer token did not match any active key. Key was revoked or mistyped. Create a new key.
TOKEN_INVALID 401 Session cookie JWT failed signature. UI-only. Log out / log in again.
TOKEN_EXPIRED 401 For cookies: JWT exp past. For account ops: the stored IG access token expired. Reconnect the IG account via the UI.
AUTH_FAILED 500 Internal failure completing OAuth. Retry; file a bug if it persists.
COOKIE_AUTH_REQUIRED 403 Endpoint accepts session cookie only — POST/DELETE /settings/api-keys refuse Bearer auth. Use the Settings UI.
SETUP_LOCKED 403 Setup is complete; mutating setup endpoints are frozen. Not reachable from /api/v1.

Validation & input · 13 codes

Code HTTP Description Recovery
VALIDATION_ERROR 400 Body/query/params failed Zod validation. Check details in dev mode; fix the offending field.
MISSING_PARAM 400 A required query param is absent. Supply the param.
INVALID_PARAM 400 Param present but unparseable. Check format (ISO date, UUID, enum).
INVALID_CODE 400 Challenge code was not exactly 6 digits. Resend as a 6-char string.
INVALID_STATUS 400 Operation not valid for the post's current status. Check the post's status.
INVALID_SCHEDULE 400 scheduledFor not strictly in the future. Send a future timestamp.
INVALID_TAGS 400 userTags only allowed on IMAGE / CAROUSEL. Remove tags for REELS/STORIES.
INVALID_MENTIONS 400 storyMentions only allowed on STORIES. Remove mentions or switch to STORIES.
INVALID_COLLABORATORS 400 collaborators not supported on STORIES. Remove collaborators.
INVALID_CROSS_POST 400 FB cross-post not supported for this type (carousel). Set crossPostToFacebook: false.
INVALID_MEDIA_TYPE 400 Uploaded file incompatible with mediaType. Match the file to its type.
INVALID_CAROUSEL 400 CAROUSEL requires 2–10 media files. Adjust mediaFileIds.length.
INVALID_WORKER_KEY 400 Worker API key failed verification. Redeploy the Worker.

Resource not-found · 1 code

Code HTTP Description Recovery
NOT_FOUND 404 Resource missing or not owned by caller. Check the id. If you own it, ensure your auth context matches.

Media pipeline · 5 codes

Code HTTP Description Recovery
MEDIA_INVALID 400 Missing storage path, unsupported MIME, or failed validation. Re-upload.
NO_MEDIA_ID 400 Post has no IG media id — cannot delete from IG. Only applies to DELETE /posts/{id}/instagram on stale records.
UPLOAD_ERROR 400 Multer upload failed — oversize, unexpected field, etc. Check size limit + field name (file).
PROCESSING_FAILED 500 Sharp image processing errored. File a bug with the source image.
VIDEO_PROCESSING_FAILED 500 FFmpeg video processing errored. Re-encode the source (H.264, AAC, MP4).

Rate limiting · 2 codes

Code HTTP Description Recovery
RATE_LIMITED 429 Exceeded per-minute or per-hour budget. Sleep for retryAfter seconds, then retry once.
LOGIN_RATE_LIMITED 429 Too many Private API logins for the same account within the safety window (default 6 h). Wait out the window.

Instagram / Graph API · 1 code

Code HTTP Description Recovery
STORIES_CANNOT_DELETE 400 IG does not allow stories to be deleted via API. Wait 24 h for expiry.

Private API / challenge · 10 codes

Code HTTP Description Recovery
PRIVATE_API_REQUIRED 400 Story mentions need Private API credentials; none configured. Save credentials via Settings → Private API.
LOGIN_FAILED 400 Instagram rejected credentials. Verify username/password; check for a challenge.
TWO_FACTOR_REQUIRED 400 Account has 2FA. Private API flow cannot proceed. Disable 2FA (not recommended) or skip Private API features.
NO_ACTIVE_SESSION 400 Challenge session expired before the code was submitted. Restart the save-credentials flow.
MISSING_ACCOUNT_ID 400 accountId missing on challenge submission. Include accountId.
CREDENTIALS_NOT_CONFIGURED 400 Story repost operation attempted before credentials were saved. Save Private API credentials first.
ALREADY_REPOSTED 400 Duplicate repost requested. Check history; the original succeeded.
REPOST_IN_PROGRESS 409 Another repost for the same source is running. Poll history until it resolves.
INVALID_STATE 400 Story repost record not in a state that permits the requested op. Inspect the record's status.
REPOST_FAILED 500 Upstream Private API error during repost. Retry; if it keeps failing, disable and inspect logs.

Cloudflare / Worker · 9 codes

Code HTTP Description Recovery
CLOUDFLARE_NOT_CONFIGURED 400 CF stack not configured for this user. Run Settings → Cloud setup.
NOT_CONFIGURED 400 Target integration not configured. Configure it.
R2_NOT_CONFIGURED 400 R2 bucket missing. Run the R2 setup step.
TOKEN_REQUIRED 400 CF API token absent. Provide or store one.
WORKER_UNREACHABLE 502 Deployed Worker cannot be reached. Check Worker status in CF dashboard; redeploy if needed.
SYNC_FAILED 500 Syncing posts/sessions with the Worker failed. Retry; check Worker logs.
ENCRYPTION_KEY_MISMATCH 400 Server + Worker disagree on encryption key. Redeploy the Worker.
WORKER_DEPLOY_FAILED 500 Automated Worker deployment failed. Retry; capture CF API errors from logs.
CLOUDFLARE_ERROR 500 Generic upstream CF failure. Check CF status.

Internal / unclassified · 2 codes

Code HTTP Description Recovery
UNKNOWN_ERROR 500 Unclassified bubble-up from a service. File a bug with x-request-id.
INTERNAL_ERROR 500 Unhandled exception reached the top-level handler. File a bug.

Related