HopBase DocsConcurrency, timeouts, and billing
HopBase concurrency caps, per-endpoint timeout behaviour and recommended client timeouts, request size limits, and exactly when a request is billed.
This page covers the runtime rules worth knowing before you integrate. For error codes and retry policy, see Error codes and retries.
Concurrency
- An account runs 5 requests at a time by default. A key can carry its own, lower cap; the smaller of the two applies.
- Chat, image generation, video submission and
/v1/messages/count_tokensall consume concurrency. Sub-agents in AI coding assistants, batch scripts and several open clients fill the cap quickly. - Over the cap you get 429 with
User concurrency limit reached (N)orAPI key concurrency limit reached (N), plusRetry-After. - Contact us to raise the cap.
A full queue is rejected, not queued
Requests beyond the cap are rejected immediately with 429; nothing waits server-side. Throttle in your client, or retry as Retry-After says.
Timeouts
| Case | Server behaviour | Suggested client read timeout |
|---|---|---|
| Chat on Gemini direct plans | A single generation that has not finished in about 100 seconds is treated as timed out and retried on another account, so total wait can be longer | 240s or more |
| Non-streaming chat elsewhere | No fixed cap; large contexts can take over a minute to first token | 300s or more |
| Synchronous image generation | Large images commonly take 30–100 seconds | 300s or more |
| Async images and video | Submission returns immediately; results come from polling | 60s is enough for the submission |
Stream long outputs and use the async endpoints for long jobs — that avoids nearly all timeout problems.
Request size
A single request body is capped at 60 MB; larger bodies return 413. Base64 images and video reach that quickly, so compress them or pass a URL where the model supports it.
Billing
| Situation | Billed |
|---|---|
| Successful request | Yes, per the model's unit (tokens / image / second) |
| Failed request (4xx, 5xx) | No |
| Stream interrupted midway, or client disconnected early | Yes, for the output already produced |
| Failed async task | No |
Also worth knowing:
- An empty balance blocks new requests: once the available balance reaches zero, new requests return 402. Requests already in flight are unaffected.
- Video submissions reserve balance: the estimated cost is reserved up front, so a positive balance can still return 402 when "reserved in flight + this estimate" exceeds it. Reservations are released when the task ends.
- Key quotas: if a key has its own quota, exhausting it returns 402 with
budget_exceeded.
Checking balance and usage
curl https://api.hop-base.com/v1/usage \
-H "Authorization: Bearer sk-your-key"The response carries balance (available balance), unit (currency, USD) and a quota object with this key's quota and usage. For itemised records, open Usage in the console.
Result links for images and video expire on different schedules — see Image generation API and Video generation.