Skip to Content
APIErrors & retries

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

StatuscodeMeaningAction
400VALIDATION_FAILEDRequest shape/query invalid; see errors[]Fix the request — retrying fails identically
401UNAUTHORIZEDMissing, malformed, expired or revoked token — or a token on a website-only operationCheck the scheme and key; a fresh token only helps when the old one expired or was revoked
403FORBIDDEN / NO_ACTIVE_PLAN / PLAN_LIMIT_EXCEEDEDBusiness denial shared with the websiteChange the plan or the action — retrying won’t help
404NOT_FOUNDNon-disclosing: unknown, foreign or misnested ids — also invalid cursorsTrack created ids yourself; never treat 404 as proof of deletion
409CONFLICTDuplicate/overlap keyword identity, website collision, rule-ownership conflictReconcile by listing before any re-create
429RATE_LIMITEDToken usage allowance exhaustedWait the Retry-After interval, then retry
500INTERNAL_ERRORUnexpected failureReport it with requestId
503PROVIDER_UNAVAILABLEInternal dependency unavailableRetry 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”

  1. Request pacing (429 RATE_LIMITED) comes with a Retry-After header (seconds). It is per-token short-term pacing — wait the indicated duration, then retry. This is unrelated to your subscription.
  2. Plan quotas (PLAN_LIMIT_EXCEEDED / QUOTA_EXCEEDED) are business denials carrying a quota extension 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.

Last updated on