Errors - Hopper

Failed requests return an OpenAI-style envelope.

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

A WebSocket that fails to open receives the same envelope as the body of a plain HTTP response, before any frame.

Authentication

Every request needs Authorization: Bearer sk_hopper_.... A missing, incorrect, or disabled key returns 401.

Credits

A key whose balance has reached zero returns 402 insufficient_quota. A streaming transcription session that reaches zero closes with code 1008.

Rate limits

Each key is limited to 2,000 requests per minute. Over that, the API returns 429 rate_limit_exceeded with Retry-After in seconds. Text to speech and voice cloning also return 429 when the model is at capacity.

Codes

Status	Code	Meaning
400	`invalid_json`	Body is not a JSON object
400	`invalid_content_type`	Transcription body is not `multipart/form-data`
400	`missing_file`	Transcription request has no `file`
400	`missing_model`	Transcription request has no `model`
400	`missing_name`	Clone request has no `name`
400	`missing_clip`	Clone request does not carry exactly one clip
400	`unsupported_audio_format`	Uploaded audio is mp3, ogg, flac, or mp4/m4a
400	`invalid_sample_rate`	`sample_rate` is not one the model accepts
400	`invalid_turn_detection`	`turn_detection` is not `balanced`, `patient`, or `responsive`
400	`invalid_transcript`	`input` is empty or not a string
400	`transcript_too_long`	`input` is over 1000 characters
400	`invalid_output_format`	`response_format` is not `wav` or `pcm`
400	`unsupported_parameter`	Request sets a generation parameter the model does not support, such as `speed`
400	`invalid_clip`	Reference clip is rejected by the cloning model
400	`invalid_scope`	`scope` is not `featured`, `all`, or `mine`
400	`invalid_limit`	`limit` is not an integer between 1 and 200
401	`invalid_api_key`	Key is missing or incorrect
401	`api_key_disabled`	Key was disabled in the console
402	`insufficient_quota`	Balance is zero
403	`voice_read_only`	Voice belongs to the Hopper library, not your organization
404	`model_not_found`	Model id is not in the catalog
404	`voice_not_found`	No voice with that id
405	`method_not_allowed`	Method is not supported on this path
413	`body_too_large`	Body is over 10 MB, or over 25 MB for transcriptions
429	`rate_limit_exceeded`	Key is over 2,000 requests per minute, or the model is at capacity
502	`upstream_unavailable`	Model server is unreachable
502	`upstream_error`	Model server returned an error
503	`model_offline`	Model has no healthy server right now
503	`verify_unavailable`	Key verification is temporarily unavailable
504	`upstream_timeout`	Model server did not respond in time