Error Reference

Error Codes

invalid_token

Meaning: Token is invalid or expired.

Fix: Re-authenticate for a fresh token.

Response: 401 { "error": "invalid_token" }

permission_denied

Meaning: Token lacks required permission.

Fix: Add permission to manifest; have merchant re-approve.

Response: 403 { "error": "permission_denied" }

plugin_not_found

Meaning: No plugin with given ID/slug.

Fix: Verify in Developer Console.

Response: 404 { "error": "plugin_not_found" }

plugin_not_installed

Meaning: Plugin not installed for target brand.

Fix: Direct merchant to install.

Response: 404 { "error": "plugin_not_installed" }

plugin_inactive

Meaning: Plugin installed but disabled.

Fix: Check health endpoint; ask merchant to re-enable.

Response: 403 { "error": "plugin_inactive" }

action_not_enabled

Meaning: Action not enabled for this install.

Fix: Check enabled_actions in brand plugin settings.

Response: 403 { "error": "action_not_enabled" }

manifest_invalid

Meaning: Manifest has validation errors.

Fix: Validate against schema in Developer Console.

Response: 422 { "error": "manifest_invalid" }

provider_unreachable

Meaning: Cannot reach your remote service.

Fix: Verify service is running and accessible.

Response: 502 { "error": "provider_unreachable" }

signature_invalid

Meaning: Request signature mismatch.

Fix: Verify webhook_secret and raw body signing.

Response: 401 { "error": "signature_invalid" }

webhook_replay_detected

Meaning: Timestamp too old.

Fix: Sync server clock (NTP); send requests promptly.

Response: 401 { "error": "webhook_replay_detected" }

rate_limited

Meaning: Too many requests.

Fix: Implement exponential backoff; cache responses.

Response: 429 { "error": "rate_limited", "retry_after": 60 }

validation_failed

Meaning: Request body invalid.

Fix: Check body against endpoint schema.

Response: 422 { "error": "validation_failed" }

health_check_failed

Meaning: Health endpoint didn't respond correctly.

Fix: Return 200 { "status": "ok" } within 5 seconds.

Response: 503 { "error": "health_check_failed" }