API Errors · CoreCited

Errors

Failures use standard HTTP status codes and one JSON shape, with a stable code you can branch on.

Error format

Every error response has the same body:

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "No brand with that id in this workspace."
  }
}

Status	Code	When	What to do
401	`missing_key`	No key was sent in Authorization or x-api-key.	Send Authorization: Bearer <key>.
401	`invalid_key`	The key is malformed, unknown, or has been revoked.	Check you copied the whole key. If it was revoked, create a new one under Team → API keys.
402	`plan_required`	The workspace is not on a plan that includes API access. This is checked on every request, so it also happens after a downgrade.	Upgrade to Agency or above. Existing keys start working again with no change.
404	`not_found`	The brand id is not a UUID, does not exist, or belongs to another workspace. These cases are deliberately indistinguishable.	List your brands with GET /api/v1/brands and use an id from there.
429	`rate_limited`	The workspace used up its requests for the current minute. All keys share one limit.	Wait the number of seconds in the Retry-After header, then retry.
500	`internal`	Something failed on our side. The response carries no detail by design.	Retry with backoff. If it persists, contact support with the time of the request.

This is the complete list. The API sends no other codes.

Retry only 429 (after Retry-After) and 500 (with backoff). Every other error will fail the same way again.
Alert a person on 401 and 402. The fix is a new key or a plan change, and no retry will help.
Treat 404 as a stale id. The brand was deleted, or the id came from another workspace. Refresh your ids from List brands.