Errors

One envelope, machine-readable codes, and what to do about each.

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	The balance can’t cover the hold. Body includes needed_cents and available_cents.
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)	The bytes haven’t landed yet, or the object is empty — finish the PUT, then resubmit.
organization_without_group	409	submit	Your organization has no group linked yet; contact Hooper.
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. error.code values:

error.code	Meaning
no_hoops	No hoop could be detected — check camera angle.
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.
timeout	Processing never reported back; swept after 24h.
unknown	Anything else. Quote the session id to support.