Errors & Rate Limits
Explains common errors and rate limits.
Error handling
Score's API uses conventional HTTP response codes to indicate the success or failure of an API request.
In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Score’s servers.
200 — OK
Everything worked as expected.
400 — Bad Request
The request was unacceptable due to a discrepancy in your request parameters.
401 — Unauthorized
No valid API key provided.
403 — Forbidden
You do not have access to the resource you are requesting
429 — Too Many Requests
Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 — Server errors
Something went wrong on Score’s end.
Handling status code: 400
The response body of these errors will be of the following structure.
[
{
"type": "Query" | "Params" | "Body",
"errors": [], // List of ZodErrors
}
]To understand what ZodError's are refer to the following document: Error Handling in Zod.
Rate limits
All requests to https://api.usescore.ai/api are rate limited to prevent overwhelming our servers with requests. Any client, authenticated or not, exceeding our defined thresholds will receive a 429 response status codes for their requests.
Current rate limit is 10 requests in a 10 second window. If you exceed the number of requests within this window you will be limited.
Score's API responds with standard HTTP headers as per draft-7 of the IETF specification which you can refer to here. The headers are as follows:
RateLimit-Limit
This header tells the client how many requests they are allowed to make in a certain period. For example, if the value is 100, the client can make 100 requests in the specified time window.
RateLimit-Remaining
This header indicates how many requests the client can still make within the current time window. For example, if the value is 75, the client has 75 requests left they can make before hitting the limit.
RateLimit-Reset
This header specifies the exact time when the current rate limit window will reset, given as a Unix epoch timestamp. This tells the client when they can start making requests again at the full rate limit.
Referring to these headers in a 429 response should give you enough information to know when you can start responding again.
Last updated