VYG Docs

Errors

Understand API errors and decide when to retry.

The error envelope

Every error from the REST API (https://api.vyg.app/v1) is a JSON object with one error object holding a machine-readable code and a human-readable message, except the external pop-up webhook (POST /v1/list-building/webhooks/{list_id}), which answers 400 as {"error":"invalid_payload","message":"…"}. See Connect an external popup tool.

{
	"error": {
		"code": "insufficient_scope",
		"message": "This needs the conversations:read permission, which this connection was not granted. Use an API key that has it; a brand admin can create one in Settings, Data API keys."
	}
}

Check the HTTP status and code. The message is for people and can change. It gives the reason and a next step, and a refused write ends with "No change was made."

insufficient_scope covers two cases, which the message tells apart. A credential without a scope gets "This needs the <scope> permission, which this connection was not granted", followed by how to get it. A brand without a feature (a beta, a plan permission or a role) gets a sentence naming the feature and who can turn it on, with the flag id in parentheses, for example "Conversation insights are not turned on for this brand. Ask VYG support to turn them on (beta:insight)."

Every response, including errors, carries an X-Request-Id header. Send your own X-Request-Id to have it echoed back; include it when you contact VYG about a failed request.

The MCP server (/mcp) reports errors differently. See MCP errors.

Codes

StatuscodeWhen
400bad_requestThe request is malformed: an invalid id, filter, sort, cursor or body, or an unknown field in a strict body.
400invalid_webhook_urlA webhook URL is not HTTPS, has credentials, or does not resolve to a public address.
401unauthorizedNo credential, or an unknown, revoked or expired one.
401legacy_credential_not_supportedA retired vyg_live_ credential. Create a new API key.
403insufficient_scopeThe credential is valid but lacks a scope the operation needs, the operation needs a sign-in, or a required feature is unavailable.
403feature_not_enabledA beta the operation needs, such as the messaging API, is not turned on for the brand.
404not_foundThe requested resource could not be found.
404conversation_not_foundA messaging send or pause found no conversation for this brand.
409conflictThe request conflicts with the current state, for example a duplicate name or key, or a stale schema_version.
409limit_reachedA fixed per-brand limit is reached, such as the 25 custom providers a brand can have. Retrying will not help until something is removed.
409idempotency_conflictAn Idempotency-Key was reused with different content.
422opted_outA messaging send to a contact who has opted out. Nothing is sent.
422outside_reply_windowA messaging send more than 30 days after the customer's last text, or to a contact who never texted.
422invalid_imageA messaging image_url failed the safety, type or size checks. Nothing is sent.
429rate_limitedToo many requests. VYG's own limits send a Retry-After header; a limit passed on from Shopify or Klaviyo says how long to wait in the message.
500internalVYG could not complete the request due to an unexpected error.
503unavailableThe service is temporarily unavailable. Retry with backoff.

The REST reference lists the statuses each operation can return. Validation messages name the field that failed, for example limit: Number must be less than or equal to 100.

Retrying

  • 400, 401, 403, 404: the request is wrong or not allowed. Change it before sending it again.
  • 409: for a schema_version conflict, read the resource again, re-apply your change and send it. For a duplicate, pick another name or key. For limit_reached (for example the per-brand custom provider limit on POST /v1/providers), remove something before trying again. For idempotency_conflict, send the original content again or use a new Idempotency-Key.
  • 422: a messaging send that cannot go out as asked: the contact opted out, the reply window has passed, or the image failed its checks. Nothing was sent. Change the request before sending it again.
  • 429: wait the number of seconds in the Retry-After header, or the wait the message gives, then retry. See Rate limits.
  • 500, 503: retry with exponential backoff and jitter.

Writes are not idempotent, except messaging sends, which take an Idempotency-Key header (see the Messaging guide). If another write times out, read the resource before retrying so you do not create it twice.

Collect endpoints

The collect host (https://cdp.vyg.app) uses the same error format and codes. A body over the size limit is 413 with bad_request. Some responses (404, 429, 500 or 503) have a {"message": "..."} body instead, so check the status first. See Collect errors.

MCP errors

The MCP server at https://api.vyg.app/mcp uses a different error format. Errors come in three forms.

Credential errors happen before the request is read. The body is flat, with error and error_description strings:

{ "error": "unauthorized", "error_description": "Authentication required." }

A 401 also carries a WWW-Authenticate header whose resource_metadata points at https://api.vyg.app/.well-known/oauth-protected-resource. MCP clients use it to start sign-in. Other credential problems use the same flat shape with the REST status, for example 403 with insufficient_scope.

Protocol errors are JSON-RPC error objects:

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32603, "message": "Internal error" } }
JSON-RPC codeMeaning
-32700The request body is not valid JSON.
-32000Wrong HTTP method (send MCP requests with POST), or, with HTTP 415, an MCP 2026-07-28 request without a JSON Content-Type.
-32001The request timed out. Retry with backoff.
-32602Invalid request parameters. Also returned when the tool name is unknown or not available to your credential. Invalid tool arguments come back as a tool error instead (see below).
-32020MCP 2026-07-28 only, with HTTP 400: the MCP-Protocol-Version, Mcp-Method or Mcp-Name header is missing or does not match the request body.
-32022MCP 2026-07-28 only, with HTTP 400: the requested protocol version is not supported. The error data lists the supported versions; pick one and retry.
-32603An unexpected error on VYG's side. Retry with backoff.

An MCP 2026-07-28 request without a JSON Content-Type (application/json) is refused with HTTP 415.

Tool errors are normal tool results with isError: true. The text starts with the same code the REST API uses, for example not_found: Customer not found, so the codes and retry rules above apply.

On this page