Errors and rate limits

{
  "name": "invalid",
  "message": "title: required",
  "data": {
    "errors": [
      { "path": "title", "message": "required" }
    ]
  }
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": { "retryAfter": 12 }
}

Every error answer has the same shape. Its message is written for people: what is wrong, and how to fix it.

string

required

The error’s name: invalid, required, unauthorized, forbidden, notfound, conflict, tooManyRequests or error.

string

What is wrong, and how to fix it.

object

The details, by error.

Show properties

object[]

One entry per field problem, each with its path and message.

integer

On a 429: the seconds to wait.

Status codes

Status	What happened	What to do
400 422	A value was refused.	Fix the fields `data.errors` names.
401	The key is wrong or revoked, or a signature is missing, stale or reused.	Check the key and its secret; Signing requests lists each message.
403	The key may not do this: its scopes or its allowlist.	Read the message: it names what is missing.
404	No such document or route, or one the key may not see.	Check the id and the key’s scopes.
409	The write conflicts with the document’s current state.	Read the current document, then try again.
429	The key’s rate limit is used up.	Wait `Retry-After` seconds.
5xx	The site failed.	Try again later.

Show message to people when it says more than the error’s name. A bare 404 for an unknown id is just notfound: say “not found” in your own words there.

What the SDKs retry

A write that timed out may still have landed. Check before you send it again: a resend is a new write.

In the SDKs: nothing to catch

The SDKs retry what is safe, then throw what is left as one class per failure, carrying the site’s own words. You catch only what you want to react to.

Laravel
TypeScript

Laravel’s exception handler takes care of the rest: every failure is logged with its site, route, status and request id, and rendered properly. A refused value becomes Laravel’s own validation response, so a controller needs no try:

use Fetchski\AttractCmsLaravel\Facades\Attract;

// 422 JSON, or a redirect back with the errors, keyed by field
Attract::testimonials()->updateTestimonial(id: $id, quote: $request->input('quote'));

NotFound renders a 404, RateLimited a 503 with Retry-After, anything else a 502.

Catch the one class you want to react to, and let the rest through:

import { NotFound } from '@fetchski/attract-cms-sdk';

const post = await site.blogPosts().getBlog({ id }).catch((error: unknown) => {
  if (error instanceof NotFound) return null;
  throw error;
});

Every list has a find…() that does exactly this for a 404.

Every class, and what it carries

The Laravel and TypeScript tabs each list them, with what is retried.

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Status codes

What the SDKs retry

In the SDKs: nothing to catch

Every class, and what it carries