Errors - Hooper API

Every error response has the same body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Input should be a valid string",
    "param": "source.url"
  }
}

Field	Meaning
`type`	The broad class — branch on this first.
`code`	A stable machine-readable reason.
`message`	Human-readable. May change; don’t parse it.
`param`	The request field at fault, when there is one (dotted path).

Every response also carries a Request-Id header (req_…). Include it when you contact support.

Types

`type`	HTTP	Meaning
`invalid_request_error`	400, 404, 409	The request is malformed, refers to something that doesn’t exist, or conflicts with current state. Fix the request.
`authentication_error`	401	Bad or missing key — see Authentication.
`insufficient_credits`	402	Your available balance can’t cover any of the video. Body includes `needed_cents`, `available_cents`, and `held_cents` when credit is reserved for videos in progress.
`rate_limit_error`	429	Slow down; honour `Retry-After`.
`api_error`	5xx	Hooper’s fault. Safe to retry with the same `Idempotency-Key`.

Codes you should handle

`code`	HTTP	Where	What to do
`parameter_invalid`	400	any	Check `param`.
`video_too_large`	400	submit	The file is over 10 GB. Nothing was held; an uploaded blob was deleted.
`upload_incomplete`	409	submit (`upload` source, `branding` images)	The bytes haven’t landed yet, or the object is empty — finish the `PUT`, then resubmit. For `branding`, the upload must have been created with an image `content_type`.
`image_invalid`	400	submit (`branding.*.upload_id`)	The uploaded image isn’t a PNG, JPEG or WebP. Nothing was held.
`branding_save_failed`	503	submit (`branding`)	Hooper couldn’t save your branding images. Nothing was held; retry with the same `Idempotency-Key`.
`idempotency_key_reused`	400	submit	Same `Idempotency-Key`, different body. Use a new key.
`idempotency_key_in_progress`	409	submit	A request with this `Idempotency-Key` is still being processed. Retry shortly; you’ll get its response.
`insufficient_credits`	402	submit	Top up, then resubmit.
`resource_missing`	404	any `{id}`	No such object for your organization.
`missing_api_key` / `invalid_api_key` / `wrong_environment`	401	any	See Authentication.
`rate_limit_exceeded`	429	any	Back off for `Retry-After` seconds.

Session failures

A session that fails does so asynchronously: status becomes failed, error is set, you receive a session.failed event, and the hold is voided. For a branding image, error.param also names the image. error.code values:

`error.code`	Meaning
`no_hoops`	No hoop could be detected. Check the camera angle. With the default `camera_setup: "stationary"`, Hooper only looks in the upper middle of the frame, so if the hoop is elsewhere, resubmit with `"panning"` (Recording options).
`no_court`	The court could not be detected.
`no_shots`	The video contained no detectable shots.
`video_too_large`	Over 1080p (or over 10 GB for a URL/Veo source). Uploaded bytes were deleted.
`source_invalid` / `source_unavailable`	The URL/Veo source was rejected or couldn’t be downloaded.
`source_too_slow`	The host sent the video slower than 1 MB/s. Nothing was charged; upload the file with `/v1/uploads` instead.
`insufficient_credits`	The measured video costs more than your credit (after any auto-recharge). Nothing was charged; uploaded bytes are kept so you can add credit and resubmit.
`image_unavailable`	A `branding` image URL didn’t answer `200` within 15 seconds, redirected more than 3 times, or pointed at a private address. `error.param` names the image (`branding.cover` or `branding.logo`).
`image_invalid`	A `branding` image isn’t a valid PNG, JPEG or WebP, or is corrupt. `error.param` names the image.
`image_too_large`	A `branding` image URL returned more than 5 MB. `error.param` names the image.
`video_composition_failed`	The video couldn’t be prepared for processing.
`timeout`	Processing never reported back; swept after 24h.
`unknown`	Anything else. Quote the session id to support.

For the three image_* codes, fix that image and resubmit. error.message says what was wrong. See Branding errors.