Errors

The API uses standard HTTP status codes plus a structured JSON error body for machine-readable detail.

Error body

{
  "error": {
    "code": "monitor_not_found",
    "message": "Monitor with ID 01HXABC... does not exist or is not visible to this key.",
    "request_id": "req_01HXDEF...",
    "details": {
      "monitor_id": "01HXABC..."
    }
  }
}

Field	Meaning
code	Stable machine-readable identifier. Safe to match on.
message	Human-readable description. Subject to copy changes; do not match on.
request_id	Quote this in support tickets.
details	Optional structured context. Shape varies by error code.

Status codes

Status	Meaning	When
400 Bad Request	Malformed request.	Invalid JSON, missing required fields, schema violations.
401 Unauthorized	No or invalid credentials.	Missing Authorization header, expired session, revoked API key.
402 Payment Required	Plan does not permit this feature.	Free tier attempting a Pro-gated feature (e.g. Knative Eventing).
403 Forbidden	Credentials valid but scope insufficient.	API key missing a required scope; non-admin user hitting an admin route.
404 Not Found	Resource does not exist or is cross-org.	Includes cases where an object exists in a different org; we never leak existence.
409 Conflict	State conflict.	Double-ack of an alert, duplicate Idempotency-Key, edit race.
413 Payload Too Large	Body exceeded a documented cap.	Batched ingest > 256 events; body > 1 MiB.
422 Unprocessable Entity	Business-logic validation failed.	Invalid enum value, cross-field constraint violation.
429 Too Many Requests	Rate-limited.	See Rate Limits. Honour Retry-After.
500 Internal Server Error	Unhandled server error.	Report to support with the request_id.
502/503/504	Transient upstream/infrastructure failure.	Retry with backoff.

Common error codes

Code	Typical status	Meaning
invalid_request	400	Request body or parameters failed schema validation.
unauthorized	401	Missing/invalid credentials.
scope_missing	403	API key lacks a required scope.
plan_gate_blocked	402	Feature requires a paid plan.
not_found	404	Generic “resource not visible to this caller”.
monitor_not_found	404	Specifically a monitor ID that doesn’t resolve.
alert_not_found	404
conflict	409	Generic state conflict.
alert_already_resolved	409
duplicate_idempotency_key	409	Same key used with different body within the 24h window.
payload_too_large	413	Body exceeds the endpoint cap.
rate_limited	429	Per-org or per-key rate limit hit.
ssrf_blocked	400	URL in the request resolves to a private or reserved address.
tier_gate_blocked	402	Feature is plan-gated (e.g. Knative Eventing, bulk import).

Silent successes

Some endpoints intentionally return 200 OK on what looks like a no-op (e.g. acking an already-acked alert, unsubscribing a non-subscriber). This keeps integrations idempotent. The response body indicates what changed:

{ "data": { "already_acknowledged": true, "acknowledged_at": "2026-04-24T10:00:00Z" } }

Troubleshooting

1. Always log request_id. Without it, support can’t find your request.
2. Check scope before assuming bugs. A 403 with scope_missing is almost always a key without the right scope for the path.
3. Rate-limit headers are authoritative. Don’t guess; read X-RateLimit-Remaining and Retry-After.
4. SSRF blocks are intentional. If a URL in your request is rejected with ssrf_blocked, check whether it resolves to an RFC1918 / link-local / loopback / metadata range. Self-hosted deployments can opt in via the YIPYAP_ALLOW_PRIVATE_TARGETS env var.