Errors

Every failure returns the same envelope — never alongside data:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Domain is not a valid hostname",
    "details": [
      { "field": "domain", "code": "INVALID_FORMAT", "message": "Domain is not a valid hostname" }
    ]
  }
}

code and message are always present; details only appears on field-level failures.

Branch on error.code, never on error.message. Messages are written for humans and change without notice; codes are a contract.

Codes

Status	Code	When
400	`BAD_REQUEST`	A parameter is malformed or a required one is missing — e.g. a date that won’t parse.
401	`UNAUTHORIZED`	No `X-API-KEY` header, or the key is unknown, revoked, or expired.
403	`FORBIDDEN`	The key is valid but the path isn’t part of the public API, or the brand belongs to another organization.
404	`NOT_FOUND`	The brand, prompt, topic, competitor or ad doesn’t exist — including a brand that’s been soft-deleted.
422	`VALIDATION_ERROR`	The payload parsed but failed validation. Look at `details`.
422	`USAGE_LIMIT_REACHED`	A write would push your subscription past its prompt/region limits. The whole batch is rolled back — nothing partial is written.
429	`RATE_LIMITED`	Too many requests. See Rate limits.
500	`INTERNAL_ERROR`	Something broke on our side. Safe to retry with backoff; if it persists, get in touch.

Field codes

Inside details[].code on a VALIDATION_ERROR:

Code	Meaning
`REQUIRED`	The field is missing or empty.
`INVALID_FORMAT`	Present but malformed (a domain that isn’t a hostname, a bad UUID).
`OUT_OF_RANGE`	A number or date outside the accepted range.
`DUPLICATE`	Conflicts with something that already exists.

Partial success on bulk writes

Bulk endpoints are not all-or-nothing in the same way. create_brand_prompts writes the valid rows and reports the rest in the response body — a 201 can still contain failures:

{
  "data": {
    "total_prompts": 12,
    "prompts_added": 10,
    "prompts_failed": 2,
    "duplicates": ["best crm for startups"],
    "invalid_regions": ["xx"],
    "errors_and_warnings": [ ]
  }
}

Check prompts_failed and errors_and_warnings even on a success status. The one exception is usage limits: if the batch as a whole would exceed your subscription, the entire mutation is rolled back and you get a 422 USAGE_LIMIT_REACHED instead — no rows are written.

Handling errors

401 — stop retrying. The key is bad, revoked, or expired; retrying won’t fix it.
403 — you’re calling an endpoint outside the public surface, or a brand your org doesn’t own. Also not retryable.
404 — treat as terminal. A soft-deleted brand starts returning it mid-integration, so handle it as “gone”, not as a transient failure.
422 — a bug in your payload. Log details and fix the caller.
429 — back off exponentially and retry. Don’t rotate keys to get around it; the per-IP backstop catches that too.
500 — retry with backoff, cap the attempts, and alert if it sticks.

Get started

Guides

Codes

Field codes

Partial success on bulk writes

Handling errors

​Codes

​Field codes

​Partial success on bulk writes

​Handling errors

Codes

Field codes

Partial success on bulk writes

Handling errors