API Responses and Error Messages

Below are some common error messages that you might encounter and what they mean.

HTTP Response CodeMeaningAction to take
200SuccessProcess the response.
400Bad requestCheck 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 grant: invalid codeThe authorization code you've provided is expired or has been redeemed for a token already. Check for unexpected retries.
401Invalid authCheck your API token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for!
404Resource not availableCheck 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.
413Request entity too largeYour limit parameter may be over 10000; reduce accordingly.
429Rate limit exceededTry again after rate limit period expires.
500, 502, 503Clever API failureWait and retry request.
501Not implementedYour client is attempting an unsupported request. Try an alternative request. Do not retry request.

Error Message/Payload Format

You should expect to receive the vast majority of responses in JSON format when using the Clever APIs. You may encounter HTML-formatted responses if:

  • You are using the incorrect token for an endpoint (e.g., using an Instant Login Bearer token when querying /v3.0/courses)
  • You are attempting to query an endpoint that doesn't exist (e.g. querying /v3.0/classes)

If you encounter HTML-formatted responses, please ensure you are using the correct token for the endpoint and that the endpoint exists. You can view existing endpoints in our public Postman Developer Collection.

Rate Limiting

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

Request:

HOST api.clever.com
GET /v1.2/students/123
AUTHORIZATION Bearer ABCD

Response headers:

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.

Request:

HOST api.clever.com
GET /v1.2/students/123
AUTHORIZATION Bearer ABC

Response headers:

Status: 429 Too Many Requests
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123

Retrying requests after errors

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.

See example exponential backoff implementations in PHP and C#.

Is Clever down?

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.