Error Handling

Praeto Dispatcher uses JSON error responses. Standard shape:

{
  "ok": false,
  "error": "error message",
  "details": {}
}

details may be a string, object, array, or omitted depending on the failure.

Common HTTP statuses

Status	Meaning	Typical Cause
`400`	Bad request	Invalid JSON, invalid URL, missing fields, payload too large
`401`	Unauthorized	Missing/invalid bearer token
`404`	Not found	Event, endpoint, or delivery does not exist for this tenant
`409`	Conflict	Idempotency key reused with different payload
`429`	Rate limited or quota exceeded	Too many requests or monthly/hard limit reached
`500`	Internal server error	Unexpected backend/database/runtime failure

Authentication errors

Missing bearer token:

{
  "ok": false,
  "error": "missing bearer token"
}

Invalid API key:

{
  "ok": false,
  "error": "invalid API key"
}

Invalid admin key:

{
  "ok": false,
  "error": "invalid admin key"
}

Idempotency conflict

Returned when the same Idempotency-Key is reused with a different payload.

{
  "ok": false,
  "error": "idempotency key already used with a different payload",
  "details": {
    "event_id": "811fad9a-d2cb-4dd2-a2e1-9bb5d90190db"
  }
}

Correct response from the publisher:

Do not retry with a different payload under the same key.
Fetch or inspect the original event.
Use a new idempotency key only if this is genuinely a different event.

Rate limit errors

Example:

{
  "ok": false,
  "error": "rate limit exceeded",
  "details": {
    "tenant_id": "default",
    "action": "events:write",
    "limit": 60,
    "current": 61,
    "window_seconds": 60,
    "window_start": "2026-04-28T09:14:00.000Z",
    "retry_after_seconds": 16
  }
}

Recommended client behavior:

Read details.retry_after_seconds.
Wait at least that long.
Retry with the same Idempotency-Key if retrying POST /v1/events.

Quota limit errors

Possible quota failures:

monthly event limit exceeded
monthly attempt limit exceeded
max endpoint count exceeded
max fan-out endpoints exceeded
payload too large

Recommended response:

inspect /v1/usage/current
inspect /v1/usage/limits
upgrade plan or reduce usage

URL validation errors

Praeto Dispatcher blocks unsafe webhook URLs. Examples:

{
  "ok": false,
  "error": "invalid url",
  "details": "url hostname is blocked for SSRF protection"
}

{
  "ok": false,
  "error": "invalid url",
  "details": "url must not include username or password credentials"
}

{
  "ok": false,
  "error": "invalid url",
  "details": "url must start with http:// or https://"
}

Blocked examples:

http://localhost:8080/webhook
http://127.0.0.1:8080/webhook
http://10.0.0.5/webhook
http://172.16.0.1/webhook
http://192.168.1.20/webhook
http://169.254.169.254/latest/meta-data
http://metadata.google.internal/computeMetadata/v1
ftp://example.com/webhook
https://user:pass@example.com/webhook

Delivery failure vs API failure

Important distinction:

POST /v1/events returning success means Praeto accepted and queued the event.
It does not guarantee every downstream webhook endpoint returned success.

Use:

GET /v1/events/{event_id}/deliveries
GET /v1/deliveries/{delivery_id}/attempts
GET /v1/endpoints/{endpoint_id}/health

for delivery status.

Retry-safe client behavior

When publishing events:

Always send an Idempotency-Key.
If the request times out or returns 5xx, retry with the same key and same body.
If the response is 409, stop and inspect the original event.
If the response is 429, wait for retry_after_seconds and retry with the same key.

Get Started

Core Concepts

API Reference

Guides

Examples

Error Handling

Error Handling

Common HTTP statuses

Authentication errors

Idempotency conflict

Rate limit errors

Quota limit errors

URL validation errors

Delivery failure vs API failure

Retry-safe client behavior

​Error Handling

​Common HTTP statuses

​Authentication errors

​Idempotency conflict

​Rate limit errors

​Quota limit errors

​URL validation errors

​Delivery failure vs API failure

​Retry-safe client behavior

Error Handling

Common HTTP statuses

Authentication errors

Idempotency conflict

Rate limit errors

Quota limit errors

URL validation errors

Delivery failure vs API failure

Retry-safe client behavior