Errors

The API uses standard HTTP status codes. Errors return a JSON body, and the codes in error_code tell you what went wrong so you can show the user a clear message.

Error Format

{
  "name": "payment-required",
  "message": "payment-required",
  "error_code": "clip_limit_reached",
  "required_plan": "pro"
}

Fields

name (string): Error category (e.g., "bad-request", "unauthenticated", "payment-required", "not-found", "conflict", "unprocessable-entity").
message (string): Description of the error. It can be terse: don’t show it to users as is.
error_code (string, optional): Machine-readable reason, on 402, 409 and 422 errors. See the tables below.
required_plan (string, optional): On 402 errors, the Klap plan that includes the action ("basic", "pro", "pro-plus").

Some 402 responses contain only error_code and message. A failed download (504) returns { "error": "Export timed out or failed." }.

Status Codes

Status	Meaning	What to do
`400`	Invalid parameters or body. `message` describes the problem	Fix the request
`401`	Missing, expired or invalid access token	Refresh the token and retry. If the refresh fails, ask the user to reconnect their Klap account
`402`	Not included in the user’s plan, plan limit reached, or subscription not active	See Payment Required
`404`	The resource doesn’t exist or isn’t in the user’s account	Check the ID
`409`	The posts can’t be scheduled	See Conflicts
`422`	Klap can’t use the video	See Unprocessable Video
`503`	Scheduling is busy	Retry shortly, with the same post IDs
`504`	A download timed out or its export failed	Check the export with Get Export
`5xx`	Klap is temporarily unavailable	Retry in a minute

Payment Required (402)

The action isn’t available on the user’s current plan or subscription. Plans are described at https://klap.app/pricing.

`error_code`	Meaning
`subscription_paused`	The user’s Klap subscription is paused. They can update it at https://klap.app/billing
`subscription_past_due`	The user’s Klap subscription is past due. They can update it at https://klap.app/billing
`video_limit_reached`	The user reached their plan’s video limit
`clip_limit_reached`	The clips this video would produce exceed the user’s remaining clip allowance
`credit_limit_reached`	The user reached their plan’s credit limit
`upload_limit_reached`	The user reached their plan’s upload limit
`export_limit_reached`	The user reached their plan’s export allowance
`payment_required`	The action requires a paid plan
`country_black_listed`	The free trial isn’t available in the user’s country: a paid plan is required

Other values are possible. Treat any other 402 as “not included in the user’s current plan”, and mention required_plan when it’s present.

Conflicts (409)

Returned by Schedule Posts. None of the posts in the request were saved.

`error_code`	Meaning
`account_disconnected`	A social account is no longer connected. The user must reconnect it at https://klap.app/calendar
`duplicate_post`	The clip already has a post on that platform
`youtube_capacity`	YouTube’s daily posting capacity is reached for that day. Choose another day
`publication_exists`	A post with this `id` already exists: an earlier request with the same post went through

Unprocessable Video (422)

Returned by Create Project from Video when Klap can’t use the video. No project is created.

`error_code`	Meaning
`invalid_video`	Klap couldn’t read the video. Use a public link or a direct link to the file
`yt_video_not_available`	The YouTube video isn’t available
`drm_protected`	The video is DRM-protected
`age_restricted`	The YouTube video is age-restricted
`not_available_in_US`	The YouTube video isn’t available in the United States
`video_too_short`	The video is too short to clip (minimum 10 seconds)
`video_too_long`	The video is longer than the user’s plan allows
`no_audio_stream`	The video has no audio
`no_video_stream`	The file has no video track

Project Error Codes

When a project ends with status "error", its error_code says why:

`error_code`	Meaning
`no_clip_generated`	Klap couldn’t find clip-worthy moments in this video
`not_enough_tokens`, `no_speech_detected`	The video doesn’t have enough speech to find clips
`video_private`	The YouTube video is private
`video_members_only`	The YouTube video is for channel members only
`video_removed`	The YouTube video was removed
`video_age_restricted`	The YouTube video is age-restricted
`external_download_failed`	Klap couldn’t download the video

Other values are possible. Treat them as “Klap couldn’t process this video”.

Object Formats