API Responses and Error Messages

❗️
Clever Complete Agreement Required
This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Use this page to understand common Clever API responses, identify likely causes of errors, and choose the right retry behavior.

Error messages

HTTP response code	Meaning	What to do
`200`	Success	Process the response.
`400`	Bad request	Check your API token, request parameters, and request body. Do not retry until you fix the request.
`400` + `Invalid grant: invalid code`	Invalid or expired authorization code	The authorization code is expired or has already been exchanged. Check for unexpected retries.
`401`	Invalid auth	Check your API token and request authentication. Do not retry until you fix the request.
`404`	Resource not available	Check your token and request URL. The resource may be unavailable, unshared, deleted, or requested with the wrong token type.
`413`	Request entity too large	Your `limit` parameter may be greater than `10000`. Reduce it and try again.
`429`	Rate limit exceeded	Wait for the rate limit window to reset, then retry.
`500`, `502`, `503`	Clever API failure	Wait and retry the request.
`501`	Not implemented	Your client is making an unsupported request. Try a different request. Do not retry the same request.

Payload format

Most Clever API responses are returned in JSON.

You may receive an HTML response instead if:

you use the wrong token type for an endpoint
you request an endpoint that does not exist

Examples:

using an Instant Login bearer token with /v3.0/courses
requesting /v3.0/classes instead of a supported endpoint

If you receive an HTML response, confirm that:

you are using the correct token for the endpoint
the endpoint exists in the Clever API

You can review current endpoints in the public Postman Developer Collection.

Rate limiting

Clever rate-limits requests at 1200 requests per minute per bearer token. This applies to instant login tokens and district tokens.

The limit is not averaged over time. The request count resets every minute.

Rate-limited responses include these headers:

X-RateLimit-Reset — Unix timestamp when the counter resets
X-RateLimit-Limit — total number of requests allowed in the period
X-RateLimit-Remaining — number of requests remaining before reset
X-RateLimit-Bucket — name of the rate-limit bucket for the request

Example request:

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

Example response headers:

Status: 200 OK
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1199
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123

If the client exceeds the rate limit, Clever returns an empty response with status 429 Too Many Requests.

Example request:

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

Example 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 fails because of a temporary problem, use exponential backoff.

For example:

wait 1 second after the first failure
wait 2 seconds after the second failure
wait 4 seconds after the third failure

If the request still fails after five retries, stop the sync and try again later.

Do not retry requests that fail because of invalid input, invalid auth, or unsupported endpoints until you fix the request itself.

Is Clever down?

A full Clever outage is uncommon, but individual parts of the API can still experience issues.

Check status.clever.com to review current system status, past incidents, or subscribe to updates.