Errors & retries
Error responses use the RFC 9457 problem format with the
application/problem+json media type:
{
"type": "urn:intentloom:problem:CONFLICT",
"title": "Conflicts with an existing keyword.",
"status": 409,
"code": "CONFLICT",
"requestId": "b9c8d7e6-1234-4a5b-9c8d-0e1f2a3b4c5d",
"detail": "Keyword already tracked with an overlapping target.",
"errors": [
{ "field": "value", "code": "INVALID_VALUE", "message": "duplicates an existing keyword" }
]
}Common fields: type (stable URN), title, status, code (stable
machine code), and requestId — always present; quote it in any
support conversation. detail is a short human summary (≤300 chars) and
errors[] lists per-field failures for validation problems.
Status codes and what to do
| Status | code | Meaning | Action |
|---|---|---|---|
| 400 | VALIDATION_FAILED | Request shape/query invalid; see errors[] | Fix the request — retrying fails identically |
| 401 | UNAUTHORIZED | Missing, malformed, expired or revoked token — or a token on a website-only operation | Check the scheme and key; a fresh token only helps when the old one expired or was revoked |
| 403 | FORBIDDEN / NO_ACTIVE_PLAN / PLAN_LIMIT_EXCEEDED | Business denial shared with the website | Change the plan or the action — retrying won’t help |
| 404 | NOT_FOUND | Non-disclosing: unknown, foreign or misnested ids — also invalid cursors | Track created ids yourself; never treat 404 as proof of deletion |
| 409 | CONFLICT | Duplicate/overlap keyword identity, website collision, rule-ownership conflict | Reconcile by listing before any re-create |
| 429 | RATE_LIMITED | Token usage allowance exhausted | Wait the Retry-After interval, then retry |
| 500 | INTERNAL_ERROR | Unexpected failure | Report it with requestId |
| 503 | PROVIDER_UNAVAILABLE | Internal dependency unavailable | Retry with backoff |
401 vs 403: 401 means the credential did not authenticate (bad key,
expired, revoked, wrong scheme). 403 means it authenticated but the
business policy denied the action. A newly created token fixes an expired
or revoked key; it fixes neither a 403 nor a token sent to a
website-only operation.
Two different “limits”
- Request pacing (
429 RATE_LIMITED) comes with aRetry-Afterheader (seconds). It is per-token short-term pacing — wait the indicated duration, then retry. This is unrelated to your subscription. - Plan quotas (
PLAN_LIMIT_EXCEEDED/QUOTA_EXCEEDED) are business denials carrying aquotaextension on the problem body:
{
"code": "PLAN_LIMIT_EXCEEDED",
"quota": { "entitlement": "tracked_keywords", "limit": 500, "usage": 500 }
}limit/usage are null when not reported. Fix these on the website
(upgrade, or delete configuration items), never by retrying.
Retrying
Reads (GET). Retry transient failures (429, 503, network errors,
timeouts) with bounded backoff — for example three attempts with
exponential waits (1s, 2s, 4s) plus jitter, honoring Retry-After
exactly whenever present. Do not retry ordinary 4xx answers: they are
deterministic and will fail identically.
Creates (POST). If a create response is lost (timeout, dropped
connection), you cannot know whether it committed — and replaying a
create that did commit returns 409 CONFLICT. Reconcile instead: list
the collection, check whether the item exists, and only create it again
if it is genuinely absent. There is no idempotency key.
Updates (PATCH). A PATCH that changes nothing is a 200 no-op, so a
simple re-apply usually converges. If concurrent writers are possible,
re-check the stored row after an uncertain response instead of assuming
the last write landed unmodified.
Deletes (DELETE). Deleting an already-deleted item returns 404.
Treat 404 after a previous successful delete as success for your end
state; distinguish it from “never existed” only by your own records.
Multi-step scripts. Each request is independent: a script that fails halfway leaves earlier writes in place. Reconcile the affected collections (from lists, not from replaying mutations) before continuing.