Developers
Errors
Every error from /api/v1 is a JSON problem details body (RFC 7807) with the HTTP status, a sentence that says what to do, and often a code your program can branch on.
The error format
Errors have the content type application/problem+json. This is the answer to a write with a key that lacks reviews:write:
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="insufficient_scope", scope="reviews:write"
X-Request-Id: 4ca641ccd9b35a28db2a51a0d2dd8903
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "This API key or app connection is missing the required scope: reviews:write. Create an API key with that scope on my.grades.com/connect, or reconnect your app and approve it.",
"code": "insufficient_scope",
"required_scopes": ["reviews:write"],
"missing_scopes": ["reviews:write"]
}
| Field | What it holds |
|---|---|
type | Always about:blank |
title | The HTTP status phrase, for example Not Found |
status | The HTTP status code, the same as the response's |
detail | What happened and what to do, in plain English, for the person who reads your logs. Its wording can change: never parse it |
code | A stable machine-readable reason, when there is one (insufficient_scope, billing_locked...). Branch on status and code |
errors | On validation errors: the messages per input, keyed body.<field>, query.<name> or path.<name> |
| more | Some errors add members of their own, such as required_scopes on a missing scope or required_plan on plan_upgrade_required |
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "One or more query values are not valid: The value must be less than or equal to 100.",
"errors": { "query.limit": ["The value must be less than or equal to 100."] }
}
X-Request-Id
Every answer of the API, success or error, carries an X-Request-Id header (32 lowercase hex characters). Log it with your errors. When you contact support@grades.com about a failed call, send that header (or its first 8 characters, which the dashboard shows as "Reference") and the time of the call, and we can find the request. Browsers can read it too: it is exposed to CORS.
Status codes and what to do
| Status | When | What to do |
|---|---|---|
400 Bad Request | A parameter or body field is missing or not valid (errors names it; an unknown body field is refused and the message lists the allowed ones). Codes such as company_required (name a business) and invalid_body | Fix the request; do not retry it unchanged |
401 Unauthorized | No credential, or one that is unknown, expired or revoked. Comes with WWW-Authenticate: Bearer realm="grades" | Check the Authorization: Bearer header; refresh an OAuth token or create a new key |
402 Payment Required | plan_upgrade_required: the business's plan does not include this (required_plan names one that does). billing_locked: the business has no active plan (trial ended or subscription lapsed); writes answer 402 and reads keep working | Show the detail to the account owner; the plan is changed in the dashboard |
403 Forbidden | insufficient_scope (the body names the scope), role_forbidden (your role in the business does not allow it), automation_not_allowed (a Zapier, Make or n8n connection outside what automation apps may do), location_group_access_required (a head-office view needs every location), or a publishable key used from an origin it does not allow | Create a key with the named scope, ask an owner for the role, or add the website to the key's allowed origins |
404 Not Found | The resource does not exist, or it belongs to a business your credential cannot see (never 403, so ids cannot be probed) | Check the uuid and which businesses the key was given |
409 Conflict | The request clashes with the current state: endpoint_exists (a webhook for this URL with other events), key_expired, not_an_hq, directory_only_company, an agent action that was already decided | Read the current state, then decide; do not retry blindly |
410 Gone | A one-time link or claim that has expired (claim_expired) | Start the flow again |
422 Unprocessable | The request is valid but cannot be applied, for example a review that already has a public reply, or review_page_empty (a review request to a review page that shows no review site). Some settings endpoints also report field errors with 422 | Change what the detail names |
429 Too Many Requests | Over a rate limit; Retry-After says how many seconds to wait. Also the monthly ceiling for AI reply drafts (without Retry-After) | Wait Retry-After seconds, then retry. See Rate limits |
500 Server Error | Something failed on our side | Retry with backoff; if it keeps failing, send us the X-Request-Id |
502 Bad Gateway | A service we depend on refused or failed: a review site refused a change we forwarded, or the AI service could not answer | Retry later; the detail says which |
503 Unavailable | The operation is briefly unavailable (for example while the same change is already running) or a feature is switched off | Retry with backoff |
Send a body with every POST, PUT and PATCH, even when the operation takes no fields: {} with Content-Type: application/json. A POST with no body at all is refused by the load balancer in front of the API with an HTML 411 Length Required page, before it reaches the API, so that one answer is not problem details.
Handle errors in code
Retry only what can succeed later: 429, 500, 502 and 503, with the wait from Retry-After or an exponential backoff. Everything else needs a change first. The retry sample on Rate limits does this in four languages.