Rate Limits & Error Handling

To ensure API stability, rate limits apply to certain endpoints.

Limits

100 requests per hour (POST)

Unlimited (GET / PUT)

Rate limits apply per IP address

HTTP Status Codes

Status	Description
400	Invalid request body or missing required fields
401	Missing or invalid API key
404	Order not found
429	Rate limit exceeded
500	Internal server error

Error Responses

All errors follow a consistent JSON format.

json

// 429 Rate Limit
{ "error": "Rate limited" }

// 400 Validation Error
{
  "error": "Validation failed",
  "details": {
    "customerName": { "_errors": ["Required"] },
    "type": { "_errors": ["Invalid enum value"] }
  }
}

// 404 Not Found
{ "error": "Order not found" }

Best Practices

Polling: Call GET /api/vendor/orders at most every 30 seconds.

Retry: On 429 or 5xx, wait and retry with exponential backoff.

Idempotency: POST always creates a new order. Check if the order already exists first.

Retry with Backoff

For rate limit errors (429), we recommend exponential backoff:

javascript

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status === 429 || res.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    return res;
  }

  throw new Error("Max retries exceeded");
}