Errors & limits

Every status code the Drizz API returns, what each common failure means, and the rate limits to design around.

Status codes, failure causes and rate limits for the Drizz API.

Rate limit	~4 requests/second, burst ~20, per client
Over the limit	HTTP 429 — back off and retry
Token life	24 hours
Upload cap	500 MB per binary
Watch out	207 on a batch means partial success — read failed_executions

Prerequisites

None.

Status codes

Code	Meaning	What to do
200	Success	Execution triggered successfully
207	Multi-Status	Batch partially succeeded — inspect failed_executions
400	Bad Request	Validate your payload and parameters
404	Not Found	Verify the test plan ID and that the app version is registered
409	Conflict	This app version already exists — bump the version or skip the upload
429	Too Many Requests	You're over the rate limit. Back off and retry
500	Server Error	Contact Drizz support
502	Bad Gateway	Retry, or check service availability

Common failures

App with package name not found

Cause	Fix
The app isn't registered in Drizz	Register it — see Managing apps
Package name mismatch	Check the exact package name, including case
Organization access issue	The app belongs to a different organization

Test plan not found

Cause	Fix
Invalid test plan ID	Confirm the ID in the web app
The plan was archived or deleted	Restore it, or create a new plan
Cross-organization access	Plan IDs don't work across organizations

File size exceeded

Cause	Fix
Binary is over 500 MB	Strip debug symbols, drop unused resources, or split by ABI

Invalid access token

Cause	Fix
Token expired — they last 24 hours	Request a fresh token at the start of each run
Wrong client credentials	Check the client ID, secret and audience
Missing or malformed x-api-key header	Send the token as x-api-key, not Authorization: Bearer

Rate limits

Limit	Value
Sustained rate	~4 requests per second, per client
Burst allowance	~20 requests
Over the limit	HTTP 429

Retry behavior

Code	Retry	Detail
429	Yes	Exponential backoff with jitter. A tight retry loop extends the rate-limited window
502	Yes	Transient. Retry with backoff
500	No	Contact [e-mail]
400	No	Fails identically every time. Fix the request
404	No	Fix the test plan ID or register the app version
409	No	The version exists. Bump the version or skip the upload

Request budget

Rule	Reason
One auth call per pipeline run, not per API call	Repeated auth calls consume the rate limit
One POST /testplan/run/batch instead of one trigger per plan	Fewer requests, better parallelism
Upload only when the app version changes	Re-uploading a registered version returns 409 and transfers up to 500 MB with no effect
Log the raw request and response in CI	The trigger response is the only machine-readable record of a run
Read failed_executions on every batch	A 207 is a partial start, not a clean run

Common mistakes

What you did	What happens
Retried a 400 five times	Same failure five times. Fix the payload
Tight retry loop after a 429	You stay rate limited longer
Treated any 2xx from batch as success	207 hides failed plans
Requested a token per API call	You'll hit the rate limit on auth alone
Assumed 404 means the API is down	It means a wrong plan ID or an unregistered version
Discarded the API response in CI	Nothing to debug with when it fails

Support

For API access and issues, contact [e-mail].

Next

• API overview — the auth model and the three-call flow

• Trigger a run — where 207 and 404 come from

• CI/CD — what a pipeline can enforce today

---

Last updated: 6 August 2026