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:

403 Forbidden
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"]
}
FieldWhat it holds
typeAlways about:blank
titleThe HTTP status phrase, for example Not Found
statusThe HTTP status code, the same as the response's
detailWhat happened and what to do, in plain English, for the person who reads your logs. Its wording can change: never parse it
codeA stable machine-readable reason, when there is one (insufficient_scope, billing_locked...). Branch on status and code
errorsOn validation errors: the messages per input, keyed body.<field>, query.<name> or path.<name>
moreSome errors add members of their own, such as required_scopes on a missing scope or required_plan on plan_upgrade_required
400 Bad Request: a query value out of range
{
  "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

StatusWhenWhat to do
400 Bad RequestA 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_bodyFix the request; do not retry it unchanged
401 UnauthorizedNo 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 Requiredplan_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 workingShow the detail to the account owner; the plan is changed in the dashboard
403 Forbiddeninsufficient_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 allowCreate a key with the named scope, ask an owner for the role, or add the website to the key's allowed origins
404 Not FoundThe 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 ConflictThe 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 decidedRead the current state, then decide; do not retry blindly
410 GoneA one-time link or claim that has expired (claim_expired)Start the flow again
422 UnprocessableThe 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 422Change what the detail names
429 Too Many RequestsOver 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 ErrorSomething failed on our sideRetry with backoff; if it keeps failing, send us the X-Request-Id
502 Bad GatewayA service we depend on refused or failed: a review site refused a change we forwarded, or the AI service could not answerRetry later; the detail says which
503 UnavailableThe operation is briefly unavailable (for example while the same change is already running) or a feature is switched offRetry 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.