Each endpoint in Sila's API may return information about limits that are applied to the endpoint.
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
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
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 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
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
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.
- The request to issue 50100 Sila exceeds the AggregateLimit's credit threshold of 50000 Sila
- 403 responses are the error code that is always returned by an
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.
RateLimitfor 60 requests in a rolling 30 day period
AggregateLimitprevents end-user from withdrawing more than 2000 Sila
AggregateLimitprevents 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,
Updated over 1 year ago