Docs
Docs pages

API reference

Errors

Errors use HTTP status codes and one JSON shape.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit: 10 requests a minute per key. Retry after 41 s.",
    "request_id": "req_Lr0d1sY2rE9q",
    "doc_url": "https://vitalsbio-console.pages.dev/docs/errors/#rate_limited"
  }
}

Every error has type, code, message, request_id and doc_url. The request id is also in the X-Request-Id header of every response, errors or not. param is added when one option is at fault. Failed calls are not metered.

StatusCodeWhat to do
400missing_video, invalid_video_b64, unsupported_sourceSend the video bytes, or video_b64 in JSON. Paths and URLs are not accepted.
400invalid_species, invalid_parameter, invalid_json, unknown_sample, invalid_scopeFix the option named in param.
401missing_api_key, invalid_api_key, api_key_revoked, api_key_expiredSee authentication. Expired and revoked keys can't be brought back; create a new one.
403insufficient_scopeThis key is limited to other endpoints. Use another key, or widen its scopes in the console.
403forbidden_originConsole sessions only work inside the console. Use a key.
404not_foundNo such route. Check the path and the /v1 prefix.
405method_not_allowedModel endpoints take POST. The Allow header says which method to use.
413file_too_large, body_too_largeKeep videos under 25 MB. Cut or re-encode the clip.
415unsupported_media_typeUse video/*, application/octet-stream or application/json.
422video_rejectedThe model could not read the video (for example, not a video file). The message says why.
429rate_limitedWait for Retry-After seconds. The clients do this for you.
429monthly_quota_exceededThe plan's video minutes for this month are used up. They reset on the 1st, UTC.
429key_cap_exceededThis key reached the monthly cap you set on it. Raise the cap in the console.
502inference_errorThe model failed on this video. Try again; if it repeats, send us the request id.
503inference_unavailableNo inference backend is reachable. Nothing ran and nothing was counted. GET /v1/health tells you when it is up. Sample calls still work.
504inference_timeoutThe call took more than 5 minutes. Use a smaller max_seconds.
500internal_errorOur fault. Retry with backoff.