Errors & limits

Built so an agent can retry safely and know when not to.

Error envelope

Every failure returns the same shape, on REST and MCP alike:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request failed validation",
    "requestId": "req_9f2b4a8c1d0e",
    "docs": "https://…/docs/reference/create_monitor",
    "details": [
      { "path": "keywords", "message": "Array must contain at least 1 element(s)" }
    ]
  }
}

requestId is also returned in the x-request-id header — quote it and we can find the exact call. docs links to the capability that failed.

Codes

Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Malformed or invalid input. `details` names the offending fields.
`401`	`UNAUTHORIZED`	Missing, expired or revoked credentials.
`402`	`USAGE_LIMIT`	Plan quota exhausted. Collection pauses; reads keep working.
`403`	`FORBIDDEN`	The credential lacks the scope this capability needs.
`404`	`NOT_FOUND`	Missing, or in a project this credential cannot reach.
`409`	`CONFLICT`	Idempotency mismatch, or a duplicate write still in flight.
`429`	`RATE_LIMIT`	Too many calls. Honour `retryAfter`.
`500`	`INTERNAL_ERROR`	Our fault. Safe to retry a keyed write.

Idempotency

Send a unique Idempotency-Key header (8–128 characters) on every write. A completed response is replayed for 24 hours, so a retry after a network timeout cannot create a second monitor.

Same key, same body → the stored response is replayed.
Same key, different body → 409 CONFLICT; the caller is confused.
Same key, still running → 409 CONFLICT, so racing retries cannot both write.
A failed write releases its key, so the caller can genuinely retry.

Retry rule

Retry 429 and 5xx with exponential backoff and jitter. Never retry 400 unchanged — it will fail identically. Only retry writes that carry the same idempotency key and identical input.

Rate limits

Plan	Requests per minute
Trial	30
Solo	60
Team	180
Agency	600

Limits are per project, and every key and connection for a project shares one bucket, so minting more keys does not raise the ceiling.

Quota

Quota applies to collection, not to reads. When a project reaches its limit new mentions stop being stored and writes that would collect more return 402 USAGE_LIMIT — existing data stays fully readable. We never bill overage automatically.