Rate limits

Limits keep one caller from crowding out the rest. Each one answers in a way you can act on.

Requests

Limit	Applies to
300 requests per minute	Each caller: an end user (by their token), otherwise the client's address — a project secret's calls included.
60 uploads per minute	Each caller's file uploads, on top of the request limit.

Over a limit, a request is refused with 429 rate_limited and a Retry-After header giving the seconds to wait. Wait that long, then retry.

Work in progress

Limit	What happens past it
One task per session. A session answers one message at a time.	A new message while a task runs: 409 session_busy. Wait for the task's end, or stop it.
Tasks per project. A project runs at most a set number of tasks at once (its concurrent_tasks_max, shown in the console).	429 rate_limited with Retry-After.
Three unfinished generations per end user. Images, videos and music count together.	429 rate_limited with Retry-After. Wait for one to finish.
16 event streams per end user, 4 per session.	A new stream past either limit ends the oldest one instead: that session's oldest, else the end user's oldest. Only while every stream the end user holds was opened in the last 10 seconds is a new one refused: 429 rate_limited; retry in a few seconds. When the service as a whole holds as many streams as it can, a new one is refused with 503 service_unavailable; retry shortly.

Credits

Starting work — a message, a generation, a transcription, a voice session — needs a spendable balance on the project's billing account. Without one the request is refused up front with 429 insufficient_credits, and without Retry-After: retrying does not help until credits are added to the project. A task already running that runs out of credits ends with a task.failed frame whose error.code is insufficient_credits.

429 insufficient_available_credits means the project still has credits, but they are all held by work already under way. It clears as that work finishes.

Retrying well

• Honor Retry-After when it is there.
• Otherwise back off exponentially, with jitter, and cap the number of attempts.
• Send an Idempotency-Key on requests that start work, so a retry after a timeout never starts the same work twice.