Flikly Developers
Operations

Errors

All error responses use this JSON shape:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Developer API rate limit exceeded.",
    "request_id": "req_01abc"
  }
}

request_id is included when available (also sent as X-Request-ID on Developer API responses). Use it when contacting support@flikly.com.

Error codes

Code
API_KEY_MISSING
API_KEY_MALFORMED
API_KEY_INVALID
API_KEY_REVOKED
API_KEY_EXPIRED
API_ACCESS_NOT_INCLUDED
SUBSCRIPTION_INACTIVE
INSUFFICIENT_ROLE
INSUFFICIENT_SCOPE
RATE_LIMIT_EXCEEDED
VALIDATION_FAILED
INTERNAL_ERROR
ASSET_NOT_FOUND
ASSET_NOT_READY
ASSET_UPLOAD_TOO_LARGE
ASSET_UNSUPPORTED_CONTENT_TYPE
ASSET_FORBIDDEN
VIDEO_JOB_NOT_FOUND
VIDEO_JOB_NOT_READY
VIDEO_JOB_FAILED
IDEMPOTENCY_CONFLICT
INSUFFICIENT_CREDITS
PLAN_LIMIT_EXCEEDED
CONCURRENT_JOB_LIMIT_EXCEEDED
AUTO_RECHARGE_FAILED
BILLING_ACTION_REQUIRED
UNSUPPORTED_VIDEO_MODEL
UNSUPPORTED_ASPECT_RATIO
UNSUPPORTED_DURATION
INVALID_SOURCE_ASSET
SPLIT_JOB_NOT_FOUND
SPLIT_JOB_NOT_READY
SPLIT_JOB_FAILED
UNSUPPORTED_SPLIT_INPUT
UNSUPPORTED_CLIP_LENGTH_PRESET
UNSUPPORTED_TARGET_PLATFORM
UNSUPPORTED_CAPTION_STYLE
UNSUPPORTED_CLIP_STYLE
JOB_NOT_FOUND
UNSUPPORTED_JOB_TYPE
WEBHOOK_NOT_FOUND
WEBHOOK_LIMIT_EXCEEDED
WEBHOOK_INVALID_URL
WEBHOOK_UNSUPPORTED_EVENT
WEBHOOK_SECRET_UNAVAILABLE
WEBHOOK_DELIVERY_FAILED
USAGE_RANGE_INVALID
USAGE_QUERY_INVALID
DEVELOPER_API_DISABLED

Billing and credits

  • INSUFFICIENT_CREDITS — Buy more credits in the main Flikly app billing section (flikly.ai/dashboard/settings/billing). The Developer API uses your existing credit pool; it does not open Stripe Checkout.
  • PLAN_LIMIT_EXCEEDED — Upgrade your plan or wait for limits to reset.
  • Automatic credit recharge (when available) is configured in main app billing, not the Developer Portal.

HTTP status mapping (common)

  • 401 — API_KEY_MISSING, API_KEY_INVALID (uniform message for invalid/revoked/expired keys)
  • 403 — API_ACCESS_NOT_INCLUDED, INSUFFICIENT_SCOPE, ASSET_FORBIDDEN
  • 402 — INSUFFICIENT_CREDITS
  • 409 — IDEMPOTENCY_CONFLICT, VIDEO_JOB_NOT_READY, SPLIT_JOB_NOT_READY
  • 429 — RATE_LIMIT_EXCEEDED, CONCURRENT_JOB_LIMIT_EXCEEDED
  • 400 — VALIDATION_FAILED, USAGE_QUERY_INVALID
  • 404 — resource not found codes (ASSET_NOT_FOUND, JOB_NOT_FOUND, etc.)