Limits Headers

Each endpoint in Sila's API may return information about limits that are applied to the endpoint.

📘

Header Labels

Two common types of information apply to a service quota which is described in the Sila API header.

• Limit: Describes the quota policy
• Remaining: Remaining request quota in the reported window

Limit and Remaining headers are prefixed with nouns RateLimit or AggregateLimit.
The purpose of the nouns is to explain the service quota limit.

The limit header also has an optional verb - credit, debit, gla_balance - postfixed to the header’s label.
The purpose of the verb is to describe the kind of action the end user is attempting to make.

Limit and Remaining headers are also described in “RateLimit Header Fields for HTTP”, which is published by the IETF.

429 Response Headers

429 responses that are caused by a limit are always a RateLimit.

This example shows the header response from a single request to /redeem for 100 Sila. The end-user wants to deposit one dollar into their bank account. It is the second time the user has to used the /redeem endpoint today.

For the purpose of this illustration pretend that /redeem is a limited endpoint with a RateLimit and AggregateLimit. The RateLimit is 1 request per day. The end-user’s Sila wallet contains 1000 Sila before their request is made. The response is throwing a 429 error.

The end-user’s request is rejected, but there’s useful information about why the request returned a 429 error. Inspecting the response header reveals the following information:

RateLimit-Limit: '1, 1;window=86400;comment="rolling 1 day, 0:00:00"'
RateLimit-Remaining: 0
AggregateLimit-Limit-debit: '50000, 50000;window=86400;comment="rolling 1 day, 0:00:00"'
AggregateLimit-Remaining-debit: 50000

The bank account the end-user was trying to fund was not credited one dollar. The end-user still has 100 Sila and they can attempt to make this request to deposit Sila with the /issue endpoint again, 24 hours after their first request earlier that day.

403 Response Headers

403 responses caused by limits are always an AggregateLimit.

This example shows the header response from a single request to /issue. The end-user wants to deposit 50100 Sila from their bank account.

In this example, /issue is a RateLimited and AggregateLimited endpoint with a AggregateLimit of 50000 Sila per day. The response has thrown a 403 error.

RateLimit-Limit: '10000, 10000;window=2592000;comment="rolling 30 days, 0:00:00"'
RateLimit-Remaining: 9999
AggregateLimit-Limit-credit: '50000, 50000;window=86400;comment="rolling 1 day, 0:00:00"'
AggregateLimit-Remaining-credit: 50000

Two different service quotas—RateLimit-Limit, and
AggregateLimit-Remaining-credit—apply to the request. However, you can deduce which limit is causing the 403 response in two different ways.

1. The request to issue 50100 Sila exceeds the AggregateLimit's credit threshold of 50000 Sila
2. 403 responses are the error code that is always returned by an AggregateLimit

200 Response Headers

Here's an example of the header response in a successful request to /redeem 1000 Sila to a wallet that already contains 30 Sila. Notice that in this example three limits apply to this protected endpoint.

1. RateLimit for 60 requests in a rolling 30 day period
2. AggregateLimit prevents end-user from withdrawing more than 2000 Sila
3. AggregateLimit prevents end-user balance from exceeding 2000 Sila

RateLimit-Limit: ‘60, 60;window=2592000;comment="rolling 30 days, 0:00:00"’,
RateLimit-Remaining: 59,
AggregateLimit-Limit-debit: ‘2000, 2000;window=86400;comment="rolling 1 day, 0:00:00"’,
AggregateLimit-Remaining-debit: 1000,
AggregateLimit-Limit-gla_balance: ‘2000, 2000;window=0;comment="single transaction limit"’,
AggregateLimit-Remaining-gla_balance: 970,

Additional Resources
https://docs.datadoghq.com/api/latest/rate-limits/