Troubleshooting Guide

API Error Format

All ORBEXA API endpoints return errors in a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "details": {}
  }
}

The code field is a machine-readable identifier suitable for programmatic handling. The message field provides a human-readable explanation. The optional details object contains additional context when available, such as which specific fields failed validation.

Authentication Errors

Code	HTTP Status	Cause	Resolution
`UNAUTHORIZED`	401	API key is missing or invalid	Verify the `X-API-Key` header contains a valid key from your dashboard
`EXPIRED_API_KEY`	401	API key has passed its expiration date	Generate a new key in the dashboard under Settings > API Keys
`SESSION_EXPIRED`	401	Login session has timed out	Log in again to obtain a fresh session
`FORBIDDEN`	403	Authenticated user lacks required permissions	Check that your account role grants access to the requested resource

Common Authentication Pitfalls

Missing header prefix — Ensure you are using the correct header format. API keys use the X-API-Key header, while OAuth tokens use the Authorization: Bearer scheme.
Whitespace in keys — Copying API keys from the dashboard can sometimes introduce leading or trailing whitespace. Trim the key before use.
Revoked keys — Revoked keys return UNAUTHORIZED immediately. If a key was recently revoked by a team member, generate a replacement.

Validation Errors

Code	HTTP Status	Cause	Resolution
`VALIDATION_ERROR`	400	Request body or query parameters fail schema validation	Check the `details` field for specific field-level errors
`INVALID_DOMAIN`	400	Domain format does not match expected pattern	Ensure the domain is a valid hostname without protocol prefix (e.g., `example.com` not `https://example.com`)
`MISSING_REQUIRED_FIELD`	400	A required parameter was not provided	Include all required fields as documented in the API Reference
`XSS_DETECTED`	400	Input contains potentially dangerous HTML or script content	Remove HTML tags and script elements from input fields
`FIELD_TOO_LONG`	400	A string field exceeds its maximum allowed length	Shorten the value to fit within the documented limit

Debugging Validation Failures

When you receive a VALIDATION_ERROR, the details object contains an array of field-level issues:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        { "field": "price", "message": "Must be a positive number" },
        { "field": "currency", "message": "Must be a valid ISO 4217 currency code" }
      ]
    }
  }
}

Review each entry in the fields array and correct the corresponding values before retrying.

Rate Limiting

Overview

ORBEXA enforces rate limits to ensure fair usage and platform stability. When a rate limit is exceeded, the API returns HTTP status 429 with the error code RATE_LIMIT_EXCEEDED.

Rate Limits by Endpoint Type

Endpoint Category	Limit	Window
UCP endpoints	100 requests	Per minute
API endpoints	60 requests	Per minute
Authentication endpoints	10 requests	Per minute
Webhook endpoints	200 requests	Per minute
WordPress plugin	3 requests per IP	Per minute

Retry-After Header

When rate-limited, the response includes a Retry-After header indicating the number of seconds to wait before sending another request:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Exponential Backoff Strategy

For automated integrations, implement exponential backoff:

After the first 429 response, wait the Retry-After duration (or 1 second if not provided)
If the retry also returns 429, double the wait time
Continue doubling up to a maximum of 60 seconds
After 5 consecutive failures, log the error and alert your monitoring system

Webhook Troubleshooting

Invalid Signature

{
  "success": false,
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Webhook signature verification failed"
  }
}

HTTP Status: 400 Cause: The HMAC signature in the request header does not match the expected value computed from the request body and your webhook secret.

Platform Signature Headers

Different platforms send signatures in different headers:

Platform	Signature Header	Algorithm
Shopify	`X-Shopify-Hmac-Sha256`	HMAC-SHA256 (Base64)
WooCommerce	`X-WC-Webhook-Signature`	HMAC-SHA256 (Base64)
Stripe	`Stripe-Signature`	HMAC-SHA256 (Hex)
ORBEXA	`X-OTR-Signature`	HMAC-SHA256 (Hex)

Common Webhook Failures

Secret rotation mismatch: If you rotated your webhook secret on the platform side but did not update it in ORBEXA (or vice versa), all signature verifications will fail. Ensure the secret matches on both sides. Encoding mismatch: Some platforms Base64-encode the signature while others use hexadecimal encoding. Verify that your verification logic matches the encoding format used by the specific platform. Body format differences: Webhook signatures are computed over the raw request body. If your receiving application parses and re-serializes the JSON before verification, the signature will not match. Always verify against the raw bytes. Delivery retries: ORBEXA retries failed webhook deliveries up to 3 times with increasing delays. If your endpoint is temporarily unavailable, it will receive the same event multiple times once it recovers. Use the event ID to deduplicate.

Integration Connection Issues

Shopify OAuth

Problem	Cause	Resolution
Invalid state parameter	OAuth state token expired or was tampered with	Restart the connection flow from the ORBEXA dashboard
Token exchange failure	Shopify API returned an error during token exchange	Verify that your Shopify store URL is correct and the store is active
Missing API credentials	Required Shopify API scopes were not granted	Disconnect and reconnect, ensuring all requested permissions are approved
Store not found	The Shopify store URL does not resolve	Confirm the store subdomain is correct (e.g., `yourstore.myshopify.com`)

WooCommerce REST API

Problem	Cause	Resolution
API key mismatch	Consumer key or secret is incorrect	Regenerate API keys in WooCommerce > Settings > Advanced > REST API
REST API not enabled	WooCommerce REST API is disabled or blocked	Enable the REST API in WooCommerce settings; check that permalinks are not set to “Plain”
SSL certificate error	The WooCommerce store uses a self-signed or expired certificate	Install a valid SSL certificate on your WooCommerce host

Connection Status Indicators

Indicator	Meaning
Connected (green)	Integration is healthy and last sync succeeded
Warning (amber)	Integration is connected but the last sync encountered non-fatal errors
Disconnected (red)	Integration has lost connectivity; re-authentication may be required
Pending (gray)	Integration setup is in progress

Sync Failures

Platform API Rate Limits

External platforms enforce their own rate limits. When ORBEXA encounters a rate limit from a connected platform during sync:

The sync pauses and retries automatically after the platform’s cooldown period
If the platform rate limit persists for more than 10 minutes, the sync is marked as Partial with a log entry indicating the interruption point

Service Unavailable (503)

A 503 response during sync indicates that the platform or a downstream service is temporarily unavailable. Resolution: Wait a few minutes and trigger a manual sync. If the issue persists beyond 30 minutes, check the platform’s status page for known outages.

Partial Sync Handling

When a sync completes partially:

Products that were successfully processed are committed and available immediately
Failed items are logged with specific error details
The next sync attempt (whether automatic or manual) will re-process only the failed items

Retry Behavior

Automatic sync retries follow this schedule:

First retry: 5 minutes after failure
Second retry: 15 minutes after first retry
Third retry: 60 minutes after second retry
After 3 failed retries, the sync is marked as Failed and a notification is sent

Data Import Errors

CSV Import Validation

The CSV importer validates each row before processing. Common issues include:

Error	Cause	Resolution
Missing required column	The CSV file lacks a `title` or `price` column header	Ensure your CSV contains at minimum: `title`, `price`
Invalid price value	The price field contains non-numeric characters or is negative	Use positive decimal numbers without currency symbols (e.g., `29.99`)
Negative inventory	The inventory count is below zero	Set inventory to `0` or a positive integer
Invalid currency code	The currency value is not a recognized ISO 4217 code	Use standard three-letter codes such as `USD`, `EUR`, `GBP`
Row too long	A field value exceeds the maximum length	Truncate descriptions to 10,000 characters; titles to 500 characters

Required Fields and Formats

Field	Required	Format	Max Length
`title`	Yes	Text string	500 characters
`price`	Yes	Positive decimal number	—
`currency`	No (defaults to account currency)	ISO 4217 three-letter code	3 characters
`description`	No	Text string (HTML not permitted)	10,000 characters
`inventory`	No (defaults to 0)	Non-negative integer	—
`image_url`	No	Valid HTTPS URL	2,000 characters
`category`	No	Text string	200 characters
`sku`	No	Alphanumeric string	100 characters

Domain Verification Issues

CNAME Not Propagated

Symptom: Domain status remains “Pending” for more than a few hours. Resolution:

DNS propagation can take up to 48 hours depending on your provider and TTL settings
Verify the CNAME record was created correctly using a DNS lookup tool
Ensure no conflicting A or AAAA records exist for the same hostname

Wrong DNS Record

Symptom: Domain verification fails with a “Record mismatch” error. Resolution:

Confirm the CNAME target matches the value shown in your ORBEXA dashboard exactly
Check for trailing dots or extra characters in the DNS record
Some providers automatically append the zone name; verify the full record value

SSL Certificate Pending

Symptom: Domain shows “Verified” but HTTPS is not working. Resolution:

SSL certificates are automatically provisioned after DNS verification succeeds
Certificate issuance typically completes within 15 minutes
If the certificate has not been issued after 1 hour, disconnect and re-add the domain to restart the process

Commerce Errors

Code	HTTP Status	Cause	Resolution
`CHECKOUT_FAILED`	400	The checkout session could not be created	Check that all required checkout fields are provided and the product is in stock
`NEGATIVE_PRICE`	422	A product price is below zero	Correct the product price to a positive value in your catalog
`INVALID_CURRENCY`	422	The currency code is not a valid ISO 4217 code	Use a recognized three-letter currency code (e.g., `USD`, `EUR`, `JPY`)
`PRODUCT_NOT_FOUND`	404	The referenced product ID does not exist	Verify the product ID and ensure the product has not been deleted
`OUT_OF_STOCK`	409	The requested quantity exceeds available inventory	Reduce the quantity or wait for inventory replenishment

Quick Reference Table

Error Code	HTTP	When It Occurs	User Action
`UNAUTHORIZED`	401	Invalid or missing API key	Check API key in request header
`EXPIRED_API_KEY`	401	Key past expiration	Generate new key in dashboard
`SESSION_EXPIRED`	401	Login timed out	Re-authenticate
`FORBIDDEN`	403	Insufficient role permissions	Contact account owner for access
`VALIDATION_ERROR`	400	Malformed request body	Review `details.fields` for specifics
`INVALID_DOMAIN`	400	Bad domain format	Remove protocol prefix and trailing paths
`MISSING_REQUIRED_FIELD`	400	Required parameter absent	Add the missing field per API docs
`XSS_DETECTED`	400	Dangerous input content	Strip HTML and script tags
`FIELD_TOO_LONG`	400	Value exceeds length limit	Shorten the field value
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Wait per `Retry-After` header
`SCAN_IN_PROGRESS`	409	Duplicate scan request	Wait for current scan to finish
`DOMAIN_NOT_FOUND`	404	No scan results exist	Submit a scan request first
`INVALID_SIGNATURE`	400	Webhook HMAC mismatch	Verify secret matches on both sides
`CHECKOUT_FAILED`	400	Checkout creation error	Validate all checkout parameters
`NEGATIVE_PRICE`	422	Price below zero	Correct product pricing
`INVALID_CURRENCY`	422	Non-ISO-4217 currency	Use standard currency codes
`PRODUCT_NOT_FOUND`	404	Product ID does not exist	Verify the product ID
`OUT_OF_STOCK`	409	Insufficient inventory	Reduce quantity or restock

Getting Help

Dashboard Notifications

System-wide issues and scheduled maintenance windows are communicated through the dashboard notification system. Check the notification bell icon for any active alerts before investigating individual errors.

Protocol Endpoint Status

The endpoint status panel on the Dashboard Home page shows real-time health for UCP, ACP, and MCP endpoints. If an endpoint shows “Degraded” or “Offline,” the issue may be platform-wide rather than specific to your account.

Diagnostic Checklist

When contacting support, gather the following information to expedite resolution:

Error code and HTTP status from the API response
Request timestamp (include your timezone)
Endpoint URL that returned the error
Request body (with any API keys or secrets redacted)
Account email associated with your ORBEXA dashboard

Support Channels

Documentation — Browse the ORBEXA Knowledge Base for detailed guides
Dashboard Help — Use the in-dashboard help widget for contextual guidance
Email Support — Reach the support team at the email address listed in your dashboard footer
Status Page — Monitor platform health and incident updates in real time

For the complete API endpoint catalog and authentication details, see Chapter 8: API Reference and Rate Limiting. For dashboard feature walkthroughs, see Chapter 9: Merchant Dashboard.

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

​Troubleshooting Guide

​API Error Format

​Authentication Errors

​Common Authentication Pitfalls

​Validation Errors

​Debugging Validation Failures

​Rate Limiting

​Overview

​Rate Limits by Endpoint Type

​Retry-After Header

​Exponential Backoff Strategy

​Webhook Troubleshooting

​Invalid Signature

​Platform Signature Headers

​Common Webhook Failures

​Integration Connection Issues

​Shopify OAuth

​WooCommerce REST API

​Connection Status Indicators

​Sync Failures

​Platform API Rate Limits

​Service Unavailable (503)

​Partial Sync Handling

​Retry Behavior

​Data Import Errors

​CSV Import Validation

​Required Fields and Formats

​Domain Verification Issues

​CNAME Not Propagated

​Wrong DNS Record

​SSL Certificate Pending

​Commerce Errors

​Quick Reference Table

​Getting Help

​Dashboard Notifications

​Protocol Endpoint Status

​Diagnostic Checklist

​Support Channels

Troubleshooting Guide

API Error Format

Authentication Errors

Common Authentication Pitfalls

Validation Errors

Debugging Validation Failures

Rate Limiting

Overview

Rate Limits by Endpoint Type

Retry-After Header

Exponential Backoff Strategy

Webhook Troubleshooting

Invalid Signature

Platform Signature Headers

Common Webhook Failures

Integration Connection Issues

Shopify OAuth

WooCommerce REST API

Connection Status Indicators

Sync Failures

Platform API Rate Limits

Service Unavailable (503)

Partial Sync Handling

Retry Behavior

Data Import Errors

CSV Import Validation

Required Fields and Formats

Domain Verification Issues

CNAME Not Propagated

Wrong DNS Record

SSL Certificate Pending

Commerce Errors

Quick Reference Table

Getting Help

Dashboard Notifications

Protocol Endpoint Status

Diagnostic Checklist

Support Channels