API reference

Accept a notification from the authenticated source

POST/functions/v1/notify

Endpoint URL

https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify

The source and owner are derived from the Bearer credential. Callers cannot provide or override source/owner identity. The inbox record and eligible delivery jobs are durable before the response is returned. Quiet hours suppress those jobs unless a Zona Plus owner has allowed critical alerts through every active schedule; the inbox record is still accepted and returned normally.

Idempotency-Key is recommended. If it is absent or blank, Zona derives a key from the source credential, normalized payload and the fixed five-minute window; identical alerts in that window replay. A retry across a window boundary can create another alert, so send a stable event key whenever possible. A malformed header is rejected. Re-sending the same key with an identical payload returns the stored notification with idempotentReplay: true and does not create a duplicate or retry push. Reusing the key with a different payload is rejected with 409 IDEMPOTENCY_CONFLICT. Optional severity is part of that payload, so changing only severity is also a conflict.

Up to five evidence images (PNG/JPEG/WebP) may be attached by sending multipart/form-data with the attachment part repeated once per image. The whole set shares the account’s server-resolved byte budget, and the images participate in idempotency: a single file keeps its own SHA-256, and reusing the key with a different set of images (added, removed, or reordered) is a conflict.

Check-ins use the same endpoint and source token. A JSON body with a checkin object (CheckinRequest) reports that a scheduled job ran (ok), began (start) or failed (fail) against a check the owner set up in the app, and is answered 200 with CheckinAccepted. A plain ok writes no alert: Zona writes one when a check-in is missed, fails or starts and never finishes, and one "back" alert when it recovers. A check-in carries no other field, Idempotency-Key is validated and then ignored (a repeated check-in is harmless), and multipart bodies cannot check in. Check-ins use the source’s per-minute plan limit, counted separately from alerts, and their own per-account budget.

Agent updates ride the same endpoint. An alert may carry an agent object (waiting, finished, failed) that reports a coding-agent session; the object is part of the payload for idempotency. A running update is the agent object alone (AgentStateRequest): it creates no inbox row and is answered 200 with AgentStateAccepted. On Zona Plus the account keeps one board entry per session and each new state resolves the session’s previous alert; on other plans agent alerts are ordinary alerts and running updates are stored nowhere. Nothing is ever sent back to the agent. Multipart requests cannot carry agent.

Authentication

Authorization: Bearer zona_live_SOURCE_TOKENIndependent one-time-issued source credential.

Headers

Header	Value	Description
`Authorization`required	`Bearer zona_live_SOURCE_TOKEN`	Independent one-time-issued source credential.
`Idempotency-Key`optional	stringlength `8–128`pattern `^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$`example `build-2026-07-20-14`	Sender-chosen unique event ID. Replays with an identical payload return the original notification; reuse with a different payload is rejected with `409 IDEMPOTENCY_CONFLICT`. Recommended. A sender that cannot set a per-event header (a generic webhook with fixed headers) may omit it: the service then derives a key from the source, the payload and the five-minute window the request arrived in, and answers with `idempotencyKeyDerived: true`. The same alert sent twice inside one window is one notification. A header that is present but malformed is still rejected.
`Content-Type`required	`application/jsonmultipart/form-data`	Media type of the request body. For multipart requests, let the HTTP library set the boundary.

Request body required

Schema one of

Option 1: object
titlestringrequired
Whitespace-trimmed title.
length 1–120
bodystringrequired
Whitespace-trimmed message.
length 1–2000
categorystring or nulloptional
length 1–80
severitystring or nulloptional
Optional visual urgency. Null or omitted uses the active theme’s neutral inbox style.
one of lowmediumhighcriticalnull
dataobjectoptional
JSON object no more than 4096 UTF-8 bytes when serialized. Reserved routing fields in the produced push are controlled by the server.
Free-form object: any keys are accepted.
todoarray of one of or nulloptional
Optional checklist delivered with the alert. Each entry is either a plain string or an object with text and an optional id. Ids must match ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$ and be unique; omitted ids are assigned positionally as i1, i2, and so on. Completion is recipient state, so an entry carrying done_at is rejected with INVALID_PAYLOAD. The recipient may tick items off or remove them in the app; the sender cannot. Replaying the same idempotency key never rewrites an existing list, so completed items survive a retry. Rejected with 403 TODO_DISABLED when the operator switch is off.
max items 20
Each item
Option 1: string
stringlength 1–200
Option 2: object
idstringoptional
length 1–64
textstringrequired
length 1–200
agentobjectoptional
A coding-agent session’s state, sent by the agent hooks. With waiting, finished or failed it rides an alert, and severity defaults to high for waiting and low for the others. running is sent alone as an AgentStateRequest and makes no alert. On Zona Plus each new state resolves the session’s previous alert (it counts as read), so the phone shows only what is current. Nothing is sent back to the agent: there is no reply or approval path.
sessionstringrequired
The agent’s own session id. Opaque; Zona stores only its SHA-256.
length 1–128pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
namestringrequired
Whitespace-trimmed agent name, such as Claude Code.
length 1–40
projectstring or nulloptional
Optional project folder name.
max length 80
statestringrequired
one of waitingrunningfinishedfailed
questionstring or nulloptional
Only with waiting (otherwise INVALID_PAYLOAD, not_allowed). The agent’s own short message about what it waits for; credentials in it are masked before it is stored.
length 1–200
Option 2: object
checkinobjectrequired
namestringrequired
The check-in name shown in the app. Whitespace-trimmed and lowercased, then matched against ^[a-z0-9][a-z0-9._-]{0,63}$.
length 1–64pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
statusstringoptional
ok (the job ran), start (it began; Zona also tells the owner about a start that never finishes) or fail (it failed; Zona writes an alert at once).
default okone of okstartfail
Option 3: object
agentobjectrequired
A coding-agent session’s state, sent by the agent hooks. With waiting, finished or failed it rides an alert, and severity defaults to high for waiting and low for the others. running is sent alone as an AgentStateRequest and makes no alert. On Zona Plus each new state resolves the session’s previous alert (it counts as read), so the phone shows only what is current. Nothing is sent back to the agent: there is no reply or approval path.
sessionstringrequired
The agent’s own session id. Opaque; Zona stores only its SHA-256.
length 1–128pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
namestringrequired
Whitespace-trimmed agent name, such as Claude Code.
length 1–40
projectstring or nulloptional
Optional project folder name.
max length 80
statestringrequired
one of waitingrunningfinishedfailed
questionstring or nulloptional
Only with waiting (otherwise INVALID_PAYLOAD, not_allowed). The agent’s own short message about what it waits for; credentials in it are masked before it is stored.
length 1–200

Example · buildComplete

{
  "title": "Build complete",
  "body": "The release build finished successfully.",
  "category": "build",
  "severity": "high",
  "data": {
    "eventId": "build-2026-07-20-14"
  }
}

Example · checkin

{
  "checkin": {
    "name": "backup",
    "status": "ok"
  }
}

Example · agentWaiting

{
  "title": "Claude Code needs you",
  "body": "Waiting for you in zona.",
  "category": "agent",
  "severity": "high",
  "agent": {
    "session": "7c1d0c9e-5b1f-4c7e-9a51-1b2e3f4a5b6c",
    "name": "Claude Code",
    "project": "zona",
    "state": "waiting"
  }
}

Example · agentRunning

{
  "agent": {
    "session": "7c1d0c9e-5b1f-4c7e-9a51-1b2e3f4a5b6c",
    "name": "Claude Code",
    "project": "zona",
    "state": "running"
  }
}

Schema NotifyMultipartRequest

titlestringrequired: Whitespace-trimmed title.
length 1–120
bodystringrequired: Whitespace-trimmed message.
length 1–2000
categorystringoptional: length 1–80
severitystringoptional: one of lowmediumhighcritical
datastringoptional: JSON-encoded object, at most 4096 UTF-8 bytes when serialized.
todostringoptional: JSON-encoded array of checklist entries, at most 20, matching the JSON body’s todo field. An agent part is rejected with INVALID_PAYLOAD (not_allowed): agent updates are JSON only.
attachmentarray of string (binary)optional: Optional evidence images, one attachment part per file, up to five. Only magic bytes are trusted: PNG, JPEG, and WebP are accepted; anything else (including SVG and renamed executables) is rejected with INVALID_PAYLOAD. The set shares the server-resolved byte budget (1 MiB on a guest account, 5 MiB for the standard plan by default, 10 MiB on Zona Plus): the sum of the images must fit the plan limit, and the whole multipart request is limited to that budget plus 64 KiB of form overhead.
max items 5

Part data: application/json
Part attachment: image/pngimage/jpegimage/webp

curl · multipart with two images

curl --request POST \
  'https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify' \
  --header "Authorization: Bearer $ZONA_SOURCE_TOKEN" \
  --header 'Idempotency-Key: build-2026-07-20-14' \
  --form 'title=Build complete' \
  --form 'body=The release build finished successfully.' \
  --form 'category=build' \
  --form 'severity=high' \
  --form 'data={"eventId":"build-2026-07-20-14"}' \
  --form 'attachment=@first.png' \
  --form 'attachment=@second.png'

Request samples

curl · reads ZONA_SOURCE_TOKEN from the environment

curl --request POST \
  'https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify' \
  --header "Authorization: Bearer $ZONA_SOURCE_TOKEN" \
  --header 'Idempotency-Key: build-2026-07-20-14' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Build complete",
    "body": "The release build finished successfully.",
    "category": "build",
    "severity": "high",
    "data": {
      "eventId": "build-2026-07-20-14"
    }
  }'

JavaScript · reads ZONA_SOURCE_TOKEN from the environment

const response = await fetch('https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZONA_SOURCE_TOKEN}`,
    'Idempotency-Key': 'build-2026-07-20-14',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Build complete',
    body: 'The release build finished successfully.',
    category: 'build',
    severity: 'high',
    data: {
      eventId: 'build-2026-07-20-14',
    },
  }),
});

const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error}`);
console.log(result);

Python · reads ZONA_SOURCE_TOKEN from the environment

import os
import requests

response = requests.post(
    "https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify",
    headers={
        "Authorization": f"Bearer {os.environ['ZONA_SOURCE_TOKEN']}",
        "Idempotency-Key": "build-2026-07-20-14",
    },
    json={
        "title": "Build complete",
        "body": "The release build finished successfully.",
        "category": "build",
        "severity": "high",
        "data": {
            "eventId": "build-2026-07-20-14",
        },
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

PowerShell · reads ZONA_SOURCE_TOKEN from the environment

$headers = @{
  Authorization = "Bearer $env:ZONA_SOURCE_TOKEN"
  'Idempotency-Key' = 'build-2026-07-20-14'
}

$body = @'
{
  "title": "Build complete",
  "body": "The release build finished successfully.",
  "category": "build",
  "severity": "high",
  "data": {
    "eventId": "build-2026-07-20-14"
  }
}
'@

Invoke-RestMethod `
  -Method Post `
  -Uri 'https://gerncrjtrdjtjvybvseb.supabase.co/functions/v1/notify' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body $body `
  -TimeoutSec 10

Responses

200For an alert, an idempotent replay: this source already sent the same Idempotency-Key with an identical payload.
The stored notification is returned (NotifyAccepted); no duplicate is created and push is not re-attempted. For a check-in, the check-in was accepted (CheckinAccepted): recorded, or, when the same status arrived within 10 seconds, debounced with recorded: false. For a running agent update, the update was accepted (AgentStateAccepted); it makes no inbox row.
Headers
Cache-Control string
always no-store
Body application/json
1. Option 1: object
  notificationIdstring (uuid)required
  sourceIdstring (uuid)required
  sourceNamestringrequired
  length 1–80
  acceptedAtstring (date-time)required
  idempotentReplaybooleanrequired
  True when an existing record was replayed instead of newly accepted.
  idempotencyKeyDerivedbooleanrequired
  True when the request carried no Idempotency-Key and the service derived one from the source, the payload and the five-minute window.
  attachmentAcceptedbooleanrequired
  True when every sent evidence image is stored for this notification.
  attachmentErrorstring or nullrequired
  Sanitized failure code when a sent image set is not stored: UPLOAD_FAILED when storage failed, IMAGE_BUDGET_REACHED when the images would pass the account’s daily image budget (1 MiB on a guest account, 10 MiB on Standard, 50 MiB on Zona Plus a UTC day); the alert is stored without them either way.
  pushAttemptedintegerrequired
  Compatibility alias. For a newly accepted notification this equals pushQueued; for an idempotent replay it is zero. It does not mean that an Expo request has already run.
  minimum 0
  pushAcceptedintegerrequired
  Compatibility field retained for older clients. notify returns zero because Expo ticket and receipt processing is asynchronous.
  minimum 0
  pushQueuedintegeroptional
  Durable delivery jobs created for eligible phones. This is zero when the alert is held by account or source quiet hours. Present on a newly accepted notification and omitted on an idempotent replay.
  minimum 0
  agentobjectoptional
  Present only when the request carried an agent object.
  boardbooleanrequired
  True when the Agent board (Zona Plus) took this update. False on other plans, while the board is switched off, and on an idempotent replay, which never changes a session.
  resolvedNotificationIdstring (uuid) or nullrequired
  The session’s previous alert that this update resolved, if any.
2. Option 2: object
  checkinobjectrequired
  namestringrequired
  The check-in name, lowercased.
  statusstringrequired
  one of okstartfail
  recordedbooleanrequired
  False when the same status arrived within 10 seconds and this request was debounced.
  statestringrequired
  The check after this check-in. new until its first ok or fail.
  one of newupdown
  nextDueAtstring (date-time) or nullrequired
  When the next check-in is due; null while the check is new and has only started.
  incidentstring or nullrequired
  opened when this fail opened an incident (and its alert); resolved when this ok closed one.
  one of openedresolvednull
  onHoldbooleanrequired
  True when the check is beyond the owner’s plan limit, or its schedule is faster than the plan allows (every 15 minutes on Standard). It is recorded but not watched.
  sourceIdstring (uuid)required
  sourceNamestringrequired
  length 1–80
  acceptedAtstring (date-time)required
3. Option 3: object
  agentobjectrequired
  statestringrequired
  always running
  storedbooleanrequired
  True when the Agent board recorded the update. False while agents.board is off, or when the update was debounced. A plan without the board (below Zona Plus) is refused with 403 PLAN_REQUIRED instead.
  sourceIdstring (uuid)required
  sourceNamestringrequired
  length 1–80
  acceptedAtstring (date-time)required
202Inbox record accepted.
Eligible push delivery jobs are durably queued, or intentionally omitted when the alert is held by quiet hours.
Headers
Cache-Control string
always no-store
Body application/json · NotifyAccepted
notificationIdstring (uuid)required
sourceIdstring (uuid)required
sourceNamestringrequired
length 1–80
acceptedAtstring (date-time)required
idempotentReplaybooleanrequired
True when an existing record was replayed instead of newly accepted.
idempotencyKeyDerivedbooleanrequired
True when the request carried no Idempotency-Key and the service derived one from the source, the payload and the five-minute window.
attachmentAcceptedbooleanrequired
True when every sent evidence image is stored for this notification.
attachmentErrorstring or nullrequired
Sanitized failure code when a sent image set is not stored: UPLOAD_FAILED when storage failed, IMAGE_BUDGET_REACHED when the images would pass the account’s daily image budget (1 MiB on a guest account, 10 MiB on Standard, 50 MiB on Zona Plus a UTC day); the alert is stored without them either way.
pushAttemptedintegerrequired
Compatibility alias. For a newly accepted notification this equals pushQueued; for an idempotent replay it is zero. It does not mean that an Expo request has already run.
minimum 0
pushAcceptedintegerrequired
Compatibility field retained for older clients. notify returns zero because Expo ticket and receipt processing is asynchronous.
minimum 0
pushQueuedintegeroptional
Durable delivery jobs created for eligible phones. This is zero when the alert is held by account or source quiet hours. Present on a newly accepted notification and omitted on an idempotent replay.
minimum 0
agentobjectoptional
Present only when the request carried an agent object.
boardbooleanrequired
True when the Agent board (Zona Plus) took this update. False on other plans, while the board is switched off, and on an idempotent replay, which never changes a session.
resolvedNotificationIdstring (uuid) or nullrequired
The session’s previous alert that this update resolved, if any.
No other fields are accepted.
400Invalid JSON, content type, field, or size-constrained value.INVALID_PAYLOADINVALID_IDEMPOTENCY_KEYINVALID_PAYLOAD
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example · invalidPayload
{ "error": "INVALID_PAYLOAD" }
Example · invalidIdempotencyKey
{ "error": "INVALID_IDEMPOTENCY_KEY" }
Example · fieldBesideCheckin
{ "error": "INVALID_PAYLOAD", "path": "title", "reason": "not_allowed" }
401Source token is absent, malformed, unknown, or revoked.INVALID_TOKEN
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "INVALID_TOKEN" }
403A server control currently rejects this optional capability, or the account’s plan does not include it (PLAN_REQUIRED: images when the daily image budget is 0, or running agent updates below Zona Plus).ATTACHMENTS_DISABLEDPLAN_REQUIREDCRITICAL_SEVERITY_DISABLEDTODO_DISABLED
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example · attachmentsDisabled
{ "error": "ATTACHMENTS_DISABLED" }
Example · planRequired
{ "error": "PLAN_REQUIRED", "path": "attachment", "reason": "not_allowed" }
Example · criticalSeverityDisabled
{ "error": "CRITICAL_SEVERITY_DISABLED" }
Example · todoDisabled
{ "error": "TODO_DISABLED" }
404A check-in names no check-in on this source.CHECKIN_NOT_FOUND
Set it up in the Zona app first; the name is case-insensitive.
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "CHECKIN_NOT_FOUND" }
405Endpoint accepts POST only, except for CORS preflight.METHOD_NOT_ALLOWED
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "METHOD_NOT_ALLOWED" }
409The Idempotency-Key was already used by this source with a different payload.IDEMPOTENCY_CONFLICT
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "IDEMPOTENCY_CONFLICT" }
413Request body exceeds 16 KiB (JSON) or the plan-resolved attachment budget plus 64 KiB (multipart).PAYLOAD_TOO_LARGE
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "PAYLOAD_TOO_LARGE" }
423The owning account is deleted, deleting, suspended, or otherwise inactive.ACCOUNT_INACTIVE
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "ACCOUNT_INACTIVE" }
429A limit was reached.RATE_LIMITEDACCOUNT_RATE_LIMITEDRATE_LIMITEDDAILY_LIMIT_REACHED
Per source a minute: 1 guest, 5 Standard, 10 Zona Plus (RATE_LIMITED). Per account: 1 a minute and 5 an hour on a guest account, 5 a minute on Standard, 10 on Zona Plus (ACCOUNT_RATE_LIMITED); check-in reports 15 (Standard) or 30 (Zona Plus) and running agent updates 15 (Zona Plus) in the last 15 minutes across the account (ACCOUNT_RATE_LIMITED); alerts per UTC day 50 guest, 300 Standard, 3,000 Zona Plus (DAILY_LIMIT_REACHED, with Retry-After set to the seconds until 00:00 UTC). Check-ins and running updates never count against the alert limits. Live values are operator-configured per plan.
Headers
Retry-After integer
Minimum retry delay in seconds; for DAILY_LIMIT_REACHED, the seconds until 00:00 UTC.minimum 1example 60
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example · sourceLimited
{ "error": "RATE_LIMITED" }
Example · accountLimited
{ "error": "ACCOUNT_RATE_LIMITED" }
Example · agentUpdatesLimited
{ "error": "RATE_LIMITED" }
Example · dailyLimit
{ "error": "DAILY_LIMIT_REACHED" }
500The request was not confirmed as accepted.INTERNAL_ERROR
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "INTERNAL_ERROR" }
503A fail-closed operator switch temporarily paused this operation.SERVICE_UNAVAILABLE
Headers
Retry-After integer
Minimum retry delay in seconds.minimum 1example 60
Body application/json · Error
errorstringrequired
requestIdstring (uuid)optional
Identifies this request in the service logs. Quote it when reporting a problem.
pathstringoptional
The field that was rejected, as the sender wrote it: title, todo[3].text, attachment[1], Idempotency-Key. The rejected value itself is never returned.
reasonstringoptional
The rule the field broke.
one of requirednot_a_stringnot_an_objectnot_an_arraynot_jsonemptytoo_longtoo_largetoo_manyunknown_valuepatternduplicatenot_allowed
limitintegeroptional
The bound that was crossed, in the field’s own unit (characters, items or bytes).
minimum 0
No other fields are accepted.
Example
{ "error": "SERVICE_UNAVAILABLE" }

Before you integrate

Send a notification

Field limits