Errors and response envelope

Every response — success or error — shares one shape.

{
  "code": 200,
  "message": "Success",
  "status": "SUCCESS",
  "data": { },
  "errors": [ ]
}

integer

The HTTP status, repeated in the body.

string

A human-readable summary. "Success" on a plain 200.

enum

Exactly SUCCESS or ERROR.

object | null

The payload. null on an error.

array

A list of { code, message, field }. Empty on success. code is the stable ERRWHK_ or ERRCORE_ identifier — match on it. field names the offending body field, or is null when the error is not field-specific.

Match on errors[].code, not on the HTTP status. Several codes share a status and mean different things — 429 is the per-key rate limit as ERRCORE_1006, but the per-subscription retry and send allowances as ERRWHK_1105 and ERRWHK_1106. One is a property of your key, the others of the subscription.

Codes every endpoint can return

HTTP	Code	When
`400`	`ERRCORE_1001`	`Api-Version` header missing, malformed, or not a version we serve. Reported on field `Api-Version`.
`401`	`ERRCORE_1004`	No `API-KEY` header at all.
`401`	`ERRCORE_1004`	The key is unknown, inactive or deleted. All three are deliberately indistinguishable — the response never confirms that a key exists.
`401`	`ERRCORE_1004`	The key resolves, but its partner row is missing or inactive. This one answers with a different message.
`403`	`ERRCORE_1005`	The key is valid but lacks the permission this route requires.
`403`	`ERRCORE_1005`	The caller’s source address is not on the credential’s IP allow-list.
`405`	`ERRCORE_1001`	A verb this path does not serve. No `Allow` header is sent — the gateway relays only `Content-Type`.
`429`	`ERRCORE_1006`	The per-API-key request budget for the current rolling minute is spent (60/min by default). Carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`.
`502`	`ERRWHK_1900`	The webhooks service was unreachable, rejected the gateway’s internal credentials, or the gateway omitted `X-Partner-Id`. All three collapse to this one code on purpose — every one of them is ours, not yours. Nothing was processed.
`503`	`ERRWHK_1902`	`webhooks.base-url` is not configured on the gateway, so no call could be attempted.
`500`	`ERRCORE_1000`	Any unmapped server-side failure. The body is always a fixed message; the real exception is logged, never returned.

405 carries no Allow header. The gateway relays only Content-Type, so a wrong verb tells you nothing about which verbs the path does serve — check the endpoint page instead.

Webhook error codes

Codes are banded by area, so the first two digits say where the failure came from.

Band	Range	Partner-visible
Subscriptions	`ERRWHK_1000–1099`	13 of 14
Deliveries, send and retry	`ERRWHK_1100–1199`	8 of 8
Events and the pull feed	`ERRWHK_1200–1299`	3 of 3
Target and egress policy	`ERRWHK_1300–1399`	10 of 10
Cursors, paging and dates	`ERRWHK_1400–1499`	4 of 4
Ingest rejections (producer surface)	`ERRWHK_1500–1599`	0 of 15
Event registry (internal)	`ERRWHK_1600–1699`	0 of 8
Gateway contract	`ERRWHK_1700–1799`	0 of 1
Secret handling	`ERRWHK_1800–1899`	1 of 2
Server edge	`ERRWHK_1900–1999`	2 of 3

The ingest, registry and gateway bands are raised on internal surfaces and never reach a partner — ERRWHK_1700 is converted to 502 ERRWHK_1900 before it leaves the gateway. Only the partner-visible codes are listed below.

Subscriptions

Code	HTTP	Meaning	When
`ERRWHK_1000`	`404`	Subscription not found	Unknown subscription id, another partner’s, or soft-deleted.
`ERRWHK_1001`	`409`	A subscription already exists for this target	A live subscription already addresses this target URL.
`ERRWHK_1002`	`409`	A PULL subscription already exists	You already have a live PULL subscription. One per partner.
`ERRWHK_1003`	`409`	Active subscription limit reached	The active-subscription cap, hit on create or on a PATCH that resumes.
`ERRWHK_1004`	`400`	Target is required	A PUSH subscription was created with no target.
`ERRWHK_1005`	`400`	Target cannot be changed	PATCH carried a target field — even one identical to the current value.
`ERRWHK_1006`	`400`	That status is set by the platform	A partner tried to set status SUSPENDED.
`ERRWHK_1008`	`422`	Delivery mode not available	deliveryMode SQS or SSE — reserved but not implemented.
`ERRWHK_1009`	`400`	Schema version must not be blank	schemaVersion present but empty or whitespace.
`ERRWHK_1010`	`400`	Schema version is not valid	schemaVersion does not match YYYY-MM.N.
`ERRWHK_1011`	`400`	Schema version is not supported	Well-formed schemaVersion this service does not implement.
`ERRWHK_1012`	`400`	Event filter is too large	eventFilter exceeds 50 entries.
`ERRWHK_1013`	`400`	Event filter entry is not valid	An eventFilter entry is blank or over 128 characters.

Deliveries, send and retry

Code	HTTP	Meaning	When
`ERRWHK_1100`	`404`	Delivery not found	Unknown delivery id, or another partner’s.
`ERRWHK_1101`	`409`	Delivery has already succeeded	Retry requested on a DELIVERED row — it would double-deliver.
`ERRWHK_1102`	`409`	Delivery is not in a retryable state	Retry requested on a row that is not FAILED or EXPIRED.
`ERRWHK_1103`	`409`	This event is already queued or in flight	A delivery for this event and subscription is already live.
`ERRWHK_1104`	`409`	This event could not be re-armed	The re-arm lost a concurrent race. Transient — repeat the request.
`ERRWHK_1105`	`429`	Too many retries for this subscription	The per-subscription retry allowance for this window is spent.
`ERRWHK_1106`	`429`	Too many sends for this subscription	The per-subscription send allowance for this window is spent.
`ERRWHK_1107`	`400`	This subscription does not receive deliveries	send was called on a PULL subscription.

Events and the pull feed

Code	HTTP	Meaning	When
`ERRWHK_1200`	`404`	Event not found	Unknown eventId on send, or not this partner’s.
`ERRWHK_1201`	`404`	No active PULL subscription	The pull feed was requested with no ACTIVE PULL subscription.
`ERRWHK_1202`	`500`	The event could not be rendered	A stored event cannot be rendered — missing category, null identity, or a canonical-JSON failure.

Target and egress policy

Code	HTTP	Meaning	When
`ERRWHK_1300`	`400`	Target must be an absolute URL	target is not an absolute URL.
`ERRWHK_1301`	`400`	Target is not a valid URL	target will not parse as a URI.
`ERRWHK_1302`	`400`	Target must use https	target is not https.
`ERRWHK_1303`	`400`	Target must not contain credentials	target carries userinfo credentials.
`ERRWHK_1304`	`400`	Target must include a hostname	target has no hostname.
`ERRWHK_1305`	`400`	Target hostname must be fully qualified	A single-label hostname.
`ERRWHK_1306`	`400`	Target hostname must be publicly resolvable	Hostname ends .local, .internal or .localdomain.
`ERRWHK_1307`	`400`	Target port is not permitted	An explicit port outside the allow-list.
`ERRWHK_1308`	`400`	Target hostname does not resolve	DNS lookup failed. Transient, not a permanent refusal.
`ERRWHK_1309`	`400`	Target resolves to a non-public address	The SSRF refusal.

Cursors, paging and dates

Code	HTTP	Meaning	When
`ERRWHK_1400`	`400`	The cursor is not valid	after is malformed, forged, from another feed, or another partner’s.
`ERRWHK_1401`	`400`	Page size is not valid	limit below 1.
`ERRWHK_1402`	`400`	Date is not a valid ISO-8601 value	startDate or endDate is not an instant or a bare date.
`ERRWHK_1403`	`400`	Start date must be on or before end date	startDate is later than endDate.

Secret handling

Code	HTTP	Meaning	When
`ERRWHK_1800`	`500`	The subscription secret could not be sealed	AES-GCM encryption failed sealing a new signing secret. Nothing was stored.

Server edge

Code	HTTP	Meaning	When
`ERRWHK_1900`	`502`	Upstream webhook service error	The webhooks service was unreachable, refused the gateway’s credentials, or the gateway omitted X-Partner-Id. Retry with backoff — nothing was processed.
`ERRWHK_1902`	`503`	Webhook requests are temporarily unavailable	webhooks.base-url is not configured on the gateway.

Shared core codes

Code	HTTP	Meaning	When
`ERRCORE_1000`	`500`	Internal server error	An unexpected error occurred. The body is always a fixed message; the real exception is logged.
`ERRCORE_1001`	`400`	Validation failed	The request failed validation. Also carries 405 on a wrong verb, since the core enum has no 405 constant.
`ERRCORE_1002`	`404`	Resource not found	The requested resource does not exist. Used for an unknown route.
`ERRCORE_1003`	`409`	Resource conflict	A database constraint refused the write.
`ERRCORE_1004`	`401`	Authentication failed	Authentication is required or invalid. Raised at the edge only.
`ERRCORE_1005`	`403`	Access denied	The key lacks the required permission, or its source address is not allow-listed. Raised at the edge only.
`ERRCORE_1006`	`429`	Rate limit exceeded	The per-API-key request budget for the current window is spent.
`ERRCORE_1008`	`503`	Service temporarily unavailable	The service is temporarily unavailable. Try again.
`ERRCORE_1009`	`502`	Downstream service unavailable	A downstream service call failed.

Retrying safely

Codes	Retry?
`ERRWHK_1308` — the target hostname did not resolve	Yes. A DNS failure is transient, not a permanent refusal.
`ERRWHK_1104` — the re-arm lost a concurrent race	Yes. Repeat the request.
`ERRWHK_1105`, `ERRWHK_1106`, `ERRCORE_1006` — rate limits	Yes, after the window.
`ERRWHK_1900`, `ERRWHK_1902`, `ERRCORE_1008`, `ERRCORE_1009`	Yes, with backoff. Nothing was processed.
Everything else `4xx`	No. Fix the request or the credential.

ERRWHK_1900 collapses three causes on purpose — the service was unreachable, it refused the gateway’s credentials, or the gateway omitted its partner header. All three are Endl-side, none are your request, and all are retryable.

Introduction

Endpoints

Errors and response envelope

Codes every endpoint can return

Webhook error codes

Subscriptions

Deliveries, send and retry

Events and the pull feed

Target and egress policy

Cursors, paging and dates

Secret handling

Server edge

Shared core codes

Retrying safely

​Codes every endpoint can return

​Webhook error codes

​Subscriptions

​Deliveries, send and retry

​Events and the pull feed

​Target and egress policy

​Cursors, paging and dates

​Secret handling

​Server edge

​Shared core codes

​Retrying safely

Codes every endpoint can return

Webhook error codes

Subscriptions

Deliveries, send and retry

Events and the pull feed

Target and egress policy

Cursors, paging and dates

Secret handling

Server edge

Shared core codes

Retrying safely