API Problems

Overview

The Asiyst REST API (https://asiyst.com/api/v1) uses standard HTTP response codes and returns machine-readable JSON error objects.

HTTP 429: Rate Limit Exceeded

Cause

Your application sent more requests within a rolling 60-second window than allowed by your current plan tier.

Standard Headers

Every API response includes rate limit telemetry:

x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 1727500800
retry-after: 14

Resolution

Implement an exponential backoff with jitter in your backend HTTP client:

async function fetchWithRetry(url: string, options: RequestInit, retries = 3): Promise<Response> {
  try {
    const res = await fetch(url, options);
    if (res.status === 429 && retries > 0) {
      const retryAfter = parseInt(res.headers.get("retry-after") || "2", 10);
      const delay = (retryAfter * 1000) + Math.random() * 500;
      await new Promise((r) => setTimeout(r, delay));
      return fetchWithRetry(url, options, retries - 1);
    }
    return res;
  } catch (err) {
    if (retries > 0) {
      await new Promise((r) => setTimeout(r, 1000));
      return fetchWithRetry(url, options, retries - 1);
    }
    throw err;
  }
}

HTTP 422: Unprocessable Entity

Cause

The request payload failed JSON Schema validation (e.g. missing required fields or invalid data types).

Example Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      { "field": "name", "issue": "Field 'name' is required and must be between 3 and 80 characters." }
    ]
  }
}

Webhook Delivery Failures

If your webhook receiver endpoint fails to capture events:

1. Verify that your server returns an HTTP 200 OK response within 5 seconds of receipt.

1. Confirm your endpoint signature verification logic using your whsec_... signing secret.

1. Check delivery history in the API Webhooks console (/dashboard/api/webhooks) to inspect response codes and payload deliveries.