Idempotency and limits

This page states how to retry a write without applying it twice, and how many requests the public API accepts.

Idempotency

To make a write safe to retry, send an Idempotency-Key header of 1 to 255 characters on any POST, PUT, PATCH or DELETE. The key is optional, and it is kept for 24 hours.

You send the same key	You get
With the same request, after the first one completed	The first response again, with the header Idempotent-Replayed: true
With a different request	IDEMPOTENCY_KEY_REUSED, status 422
While the first request is still running	IDEMPOTENCY_IN_PROGRESS, status 409; after 60 seconds, a retry runs afresh

A response with status 401, 403 or 429, a server error and a validation failure are not stored, so the key stays free for your retry.

Eight AIP authoring operations keep their own job idempotency instead: creating an audio source, creating a draft, replaying, patching an intent policy, drafting a fix, applying it, preparing and editing a policy. A request that would start a job already running answers JOB_ALREADY_EXISTS, status 409, with the running job’s id in its details, so poll that job instead of starting another.

Rate limits

Each API key draws on two budgets per minute, and the organization on a third.

Bucket	Counts	Budget
read, per key	GET requests	300 a minute
write, per key	POST, PUT, PATCH and DELETE requests	60 a minute
org, per organization	Every public call, from any key or agent	1,200 a minute

Every response carries two headers. RateLimit-Policy states the three budgets, and RateLimit names the tightest bucket, with the requests left and the seconds until it resets.

Over a budget, the API answers TOO_MANY_REQUESTS, status 429, with a Retry-After header: wait that many seconds before you retry.