> 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

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

<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*