> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/automate-and-integrate/errors-and-limits.md).

# Errors & limits

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

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

## Common failures

### App with package name not found

| Cause                             | Fix                                                               |
| --------------------------------- | ----------------------------------------------------------------- |
| The app isn't registered in Drizz | Register it — see [Managing apps](/your-account/managing-apps.md) |
| 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 `support@drizz.dev`                                                         |
| **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 `support@drizz.dev`.

## Next

* [API overview](/automate-and-integrate/api-overview.md) — the auth model and the three-call flow
* [Trigger a run](/automate-and-integrate/trigger-a-run.md) — where 207 and 404 come from
* [CI/CD](/automate-and-integrate/ci-cd.md) — what a pipeline can enforce today

***

*Last updated: 6 August 2026*