Limits
Spending
Your balance is the hard limit: while it is at or below $0, every request is refused with 400 insufficient_credits before it runs, free models included. A request is charged when it finishes, so the one that uses up the last of the balance can take it below $0; the next one is refused until you add credits. Each key can carry its own credit limit, optionally resetting daily, weekly or monthly, and an expiration; a key that has used its limit gets 400 key_budget_exceeded while the account may still have credits. See Create an API key.
Video jobs and deep research hold their estimated cost against your balance when they start and settle to the actual cost when they finish; a failed job releases the hold.
Rate limits
Rate limits are per key, as requests per minute and tokens per minute, and are set by us for your account. Responses carry the key's limits, so a client can pace itself:
| Header | Meaning |
|---|---|
x-oceantoken-key-rpm-limit | Requests allowed per minute on this key |
x-oceantoken-key-tpm-limit | Tokens allowed per minute on this key |
x-oceantoken-key-spend / x-oceantoken-key-budget | What this key has spent, and its credit limit |
Exceeding either rate returns 429 rate_limited with a Retry-After header giving the seconds until the minute window resets. A header whose limit is not set on the key is left out.
Separately, each model's channels have their own capacity. When one is busy the gateway moves the request to another channel of the same model, if it has one (Retries and failover). When every channel of a model is busy you get 429 provider_overloaded; that is the moment to retry with backoff or switch models. If your application needs sustained throughput beyond what your key allows, contact us and we will raise it.
Request size
The whole request, JSON or multipart, may be at most 10 MB. That is a gateway limit and cannot be raised per account. For images and audio, send a URL or upload the file where the endpoint allows it rather than embedding a large base64 payload.
Timeouts
A synchronous request is held open for at most 240 seconds, measured from the start of the request to the last byte of the response. Past that the connection is closed and the client sees 504 timeout. Long text generations should use "stream": true; a stream stays open as long as tokens keep flowing. Video generation is a job you poll, so it is never affected.
Retention
| What | Kept for |
|---|---|
| Image and video download URLs in API responses | 24 hours. Download the file promptly; the URL is not a permanent address. |
A stored Idempotency-Key response | 24 hours |
| Request content: the prompts and responses of your requests | 365 days after the request, then deleted automatically. You can ask for it to be deleted sooner by writing to support@oceantoken.ai |
| Files you upload, and images, audio and video generated for you | 30 days after upload or generation, then deleted automatically. A saved conversation keeps its text, but images and files in it older than 30 days no longer display. |
| Usage and billing records: each request's model, token counts, cost and time | While your account is open, and afterwards for as long as legally or commercially reasonably required. Deleting request content does not delete them; your balance and invoices are built from them |
| Saved chat conversations in the console | 365 days after they were last updated, then deleted automatically. You can delete one yourself at any time |
The console has no setting to change these periods or where requests are processed. These periods are the ones the privacy policy states; it is the full statement of what is stored, who processes it and where, and how to have your records deleted when you close your account.
Model access
An account can be limited to a set of models. GET /v1/models lists what your key can call; anything outside it returns 403 model_not_allowed. The console's Models page shows the same set.