Pixii enforces rate limits at the organization level. All API keys belonging to the same organization share the same limits — it does not matter how many keys your organization has or which key is used to make the request.

Rate limits apply to **job submission endpoints only**. Job status polling (`GET /v1/api/jobs/{job_id}`) is not rate limited.

## Limits

| Window       | Limit        |
| ------------ | ------------ |
| Per minute   | 10 requests  |
| Per day      | 500 requests |

## Rate limit headers

Every job submission response includes rate limit headers so you can track your usage and throttle your requests proactively:

| Header                             | Description                                     |
| ---------------------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit-Minute`        | Maximum requests allowed per minute             |
| `X-RateLimit-Remaining-Minute`     | Requests remaining in the current minute window |
| `X-RateLimit-Limit-Day`           | Maximum requests allowed per day                |
| `X-RateLimit-Remaining-Day`       | Requests remaining in the current day window    |

## When a limit is exceeded

When you exceed a rate limit, Pixii returns a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying.

## Best practices

- Monitor `X-RateLimit-Remaining-Minute` and back off when it approaches zero — don’t wait for a 429.
- For large batch jobs, space out your requests rather than submitting all at once.
- Use the `Retry-After` value from the response — don’t guess or use a fixed delay.
- Remember limits are per organization, not per API key — all your keys share the same bucket.
