|HTTP Response Code||Meaning||Action to take|
|Success||Process the response.|
|Bad request||Check your API token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for!|
|Invalid auth||Check your API token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for!|
|Resource not available||Check your API token and request URL - you may be using the wrong token or the resource may have been unshared with your application or deleted.|
|Request entity too large||Your |
|Rate limit exceeded||Try again after rate limit period expires.|
|Clever API failure||Wait and retry request. If you see these regularly, reach out to [email protected].|
|Not implemented||Your client is attempting an unsupported request. Try an alternative request. Do not retry request.|
Requests to Clever are rate-limited. Requests are limited to 1200 requests per minute per Bearer Token (instant login or district). These limits are not averages; rather, the allowed count of requests resets every minute.
Rate-limited requests contain these HTTP response headers:
- X-RateLimit-Reset: Unix timestamp when the rate limit counter will be reset.
- X-RateLimit-Limit: The total number of requests allowed in a time period.
- X-RateLimit-Remaining: Number of requests that can be made until the reset time.
- X-RateLimit-Bucket: Name of the rate-limit bucket for this request
HOST api.clever.com GET /v1.2/students/123 AUTHORIZATION Bearer ABCD
Status: 200 OK X-RateLimit-Limit: 1200 X-RateLimit-Remaining: 1199 X-RateLimit-Reset: 1394506274 X-RateLimit-Bucket: abc123
In case the client hits a rate limit, an empty response with a
429 Too Many Requests status code is returned.
HOST api.clever.com GET /v1.2/students/123 AUTHORIZATION Bearer ABC
Status: 429 Too Many Requests X-RateLimit-Limit: 1200 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1394506274 X-RateLimit-Bucket: abc123
When a request against the Clever API fails, use a retry strategy with exponential backoff (i.e. wait 1 second after first error, then 2, then 4, etc.). If you are unable to receive a successful response after five retries, you may want to cease the sync and resume at a later time.
It's unlikely that our APIs are down, but parts of the API naturally have outages here and there. Check status.clever.com to see how Clever is doing or review past outages. You can even subscribe to notifications so you'll always know what's going on.