# Rate Limits and Concurrency

Gateman uses three separate controls that are easy to conflate:

- **Concurrency** controls how many requests or provider-bound operations may execute at the same time.
- **Rate limiting** controls how frequently requests may be made during an applicable period.
- **Operation accounting** measures accepted billable capability invocations against an account's included allowance.

These controls can apply independently. A request can be within a frequency limit but still be rejected because current admission capacity is unavailable. A request can also be admitted and consume an operation even when execution later fails or the external provider rejects it. See [Operation Accounting](https://docs.getgateman.com/operation-accounting/) for the complete allowance and consumption rules.

## Application concurrency

Authenticated requests from the same application share Gateman's application-level admission capacity across applicable authenticated routes. HMAC and Ed25519 requests use the same application-level controls.

When application admission capacity is temporarily unavailable, Gateman may return HTTP `429` with the error `app_concurrency_limit_exceeded`. This rejection occurs before operation reservation and does not consume a billable operation. It does not mean that the application is disabled or that its monthly allowance is exhausted.

Application admission is separate from provider-bound admission and from endpoint request-frequency controls.

## Provider-bound concurrency

Gateman also manages concurrent provider-bound operations on applicable capability paths. This is shared application-level provider-bound capacity, not a separate fixed allowance for each provider. Provider-bound operations involving different external providers can therefore compete for the same application's applicable capacity.

Provider-bound admission is separate from general application concurrency. Not every capability route uses it. Staging and development capture paths may behave differently when no external provider request is made.

Provider-bound admission failure may return HTTP `429` with a Gateman-generated response. Ordering is capability-specific: production email and SMS provider-bound admission occurs before operation accounting, while staging/development captures reserve immediately before capture and other capabilities follow their own contracts. Do not assume that every provider-bound rejection is non-billable; see [Operation Accounting](https://docs.getgateman.com/operation-accounting/) and [Idempotency](https://docs.getgateman.com/idempotency/).

## Endpoint request-frequency limits

Some endpoints apply request-frequency controls independently of concurrency. The current public example is public configuration retrieval; providers may impose additional independent limits.

These controls are endpoint-dependent. Excessive frequency may produce HTTP `429`, and `Retry-After` may indicate when another attempt can be made. A request rejected by an endpoint frequency control before operation reservation does not consume a billable operation.

Where Gateman publishes a specific request-frequency limit, the applicable threshold and conditions are documented in the individual capability reference. Internal concurrency and protective infrastructure limits are not published.

Gateman does not define a universal published request-frequency limit across all authenticated API calls. Some capabilities have their own documented limits.

## Provider rate limits

External providers may enforce their own quotas, throttling, and throughput restrictions. These are independent of Gateman's application and provider-bound admission controls.

A provider may return HTTP `429` or another provider-specific failure. Depending on the capability, Gateman may preserve provider-native response information or translate it into a Gateman response. `Retry-After` is not guaranteed for every provider response.

Provider throttling can occur after Gateman accepts a billable operation. In that case, the operation remains consumed. Gateman does not provide a universal email or SMS throughput guarantee, and the official clients do not automatically retry provider operations.

## HTTP rejection behaviour

The same HTTP status can represent different conditions. Inspect the response status, body, headers, and capability contract together.

| Condition | Typical response | Operation consumption |
| --- | --- | --- |
| Application concurrency admission rejected | Gateman `429` | No |
| Provider-bound admission rejected | Gateman `429` | Depends on the capability's reservation order |
| Endpoint request-frequency limit reached | Gateman `429` | No when rejected before reservation |
| External provider rate limit reached | Provider-dependent response | Consumed if accepted for execution |
| Monthly operation allowance exhausted | Gateman `403` | No additional operation |
| Cloudflare edge protection rejects the request | Cloudflare-generated response | No Gateman operation if the request never reaches Gateman |

Not every `429` has the same cause, body, or retry behavior. See [Errors and Responses](https://docs.getgateman.com/errors-and-responses/) for the wider response contract.

## Retry-After and safe retries

Some Gateman-generated admission or frequency-limit responses include `Retry-After`. A provider response may also include retry information, but it may be absent or capability-specific. Cloudflare-generated responses may not use Gateman's response format or headers.

The official PHP, Node.js, Python, and Go clients preserve received HTTP status and headers. They do not automatically retry failed requests. Respect `Retry-After` when it is present and applicable.

### Definitively rejected before execution

A request known to have been rejected before operation admission can generally be attempted again later, subject to the capability's request requirements.

Credential-disclosure routes have an additional rule: a claimed credential-request identifier cannot be reused, even if a later part of that request was rejected. A new attempt may require a new identifier and signature.

### Outcome uncertain

Do not blindly retry when an external provider may already have accepted the request. This is especially important for payments, email, SMS, and other consequential provider-side operations.

Use capability-specific idempotency where supported. Follow the guidance in [Errors and Responses](https://docs.getgateman.com/errors-and-responses/) and the selected capability reference.

## Cloudflare edge protection

Gateman operates behind Cloudflare, which may reject traffic before it reaches the application. Cloudflare protections are distinct from Gateman's application-level controls.

An edge rejection may use a Cloudflare-generated status and body, may omit `X-Gateman-Request-ID`, and may not include Gateman-specific `Retry-After` handling. A request rejected entirely at the edge does not enter Gateman operation accounting.

Cloudflare protection settings and thresholds are not part of Gateman's public API contract.

## Related references

- [Contract v1](https://docs.getgateman.com/contract-v1/)
- [Authentication and signing](https://docs.getgateman.com/authentication/)
- [Environments](https://docs.getgateman.com/environments/)
- [Errors and Responses](https://docs.getgateman.com/errors-and-responses/)
- [Operation Accounting](https://docs.getgateman.com/operation-accounting/)