{
"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). |
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. |