Collect errors

The collect endpoints on https://cdp.vyg.app (POST /cdp/ingest and POST /cdp/events) use the same error format as the REST API on api.vyg.app: one error object holding a machine-readable code and a human-readable message. The codes are the ones listed in Errors.

{
	"error": {
		"code": "bad_request",
		"message": "Body must be a JSON object with an \"events\" array."
	}
}

Some responses have a {"message": "..."} body and no X-Request-Id:

• 404 {"message":"Not Found"} for a method or path the host does not serve.
• 429 {"message":"Too Many Requests"} when the request rate limit is exceeded.
• 500 or 503 with a message body when the request cannot be completed.

Check the HTTP status first. Read error.code only when the body has an error object. The message is for people and can change.

Every response with an error object carries an X-Request-Id header. Send your own X-Request-Id (up to 128 printable characters) to have it echoed back; browsers may send it and read it back. Include it when you contact VYG about a failed request.

Some errors carry extra fields next to error, never inside it:

• rejected: on a 400 for events that carry a scope, the offending events and their JSON paths.
• accepted and failed: on a 503 where only some events were accepted. See Retrying.

A partial failure on /cdp/events looks like this:

{
	"error": {
		"code": "unavailable",
		"message": "Some events were queued and some were not. Retry only the events listed in \"failed\". The others are already queued, and sending them again would record them twice."
	},
	"accepted": 1,
	"failed": [0]
}

Retrying

• 400, 401, 403, 404, 413: do not retry unchanged. Fix the request first.
• 429: retry with exponential backoff and jitter. These responses have no Retry-After header.
• 500, 503: retry with exponential backoff. When a /cdp/events 503 carries failed, resend only the events at those indexes in your events array; the accepted ones have already been received. A 503 with an error object and no failed means no events were accepted, so resend the whole batch. A 500 or 503 with only a message field does not say which events were accepted, so a resend may record some events twice.

Before 2026-09-28

The collect endpoints used the format {"error": "<code>", "error_description": "..."}, with their own codes. See the migration guide for the old codes and what replaced them.