Rate Limits and Error Codes

The Synaptiq API enforces rate limits to ensure fair usage and platform stability. Limits vary by your subscription plan and the type of API key used.

Rate Limit Tiers

| Plan | Requests per Minute | Requests per Day | Concurrent Connections | |--------------|---------------------|-------------------|------------------------| | Starter | 60 | 10,000 | 5 | | Pro | 300 | 100,000 | 25 | | Enterprise | 1,500 | Unlimited | 100 |

Rate limits apply per API key. If your organization uses multiple keys, each key has its own independent limit.

Endpoint-Specific Limits

Some endpoints have additional per-endpoint limits to protect resource-intensive operations:

| Endpoint | Starter | Pro | Enterprise | |-------------------------------|---------------|---------------|---------------| | POST /v1/chat | 30/min | 150/min | 750/min | | POST /v1/chat (streaming) | 15/min | 75/min | 400/min | | GET /v1/analytics/* | 20/min | 100/min | 500/min | | POST /v1/leads | 30/min | 150/min | 750/min | | GET /v1/leads/search | 20/min | 100/min | 500/min | | All other endpoints | 60/min | 300/min | 1,500/min |

Rate Limit Headers

Every API response includes headers that report your current rate limit status:

| Header | Description | |---------------------------|--------------------------------------------------------------------| | X-RateLimit-Limit | The maximum number of requests allowed in the current window. | | X-RateLimit-Remaining | The number of requests remaining in the current window. | | X-RateLimit-Reset | Unix timestamp (seconds) when the current rate limit window resets. | | X-RateLimit-RetryAfter | Seconds to wait before retrying (only present on 429 responses). |

Example Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1743868920

Example 429 Response Headers

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743868920
X-RateLimit-RetryAfter: 23

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. You have made too many requests. Please retry after 23 seconds.",
    "retryAfter": 23,
    "limit": 300,
    "doc_url": "https://synaptiqintel.com/docs/api-reference/rate-limits"
  }
}

Recommended Retry Strategy

Implement exponential backoff with jitter to handle rate limits gracefully:

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

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(
      response.headers.get("X-RateLimit-RetryAfter") || "5"
    );
    const jitter = Math.random() * 1000;
    const delay = retryAfter * 1000 + jitter;

    console.log(`Rate limited. Retrying in ${Math.round(delay / 1000)}s...`);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Max retries exceeded due to rate limiting.");
}

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "error_code_string",
    "message": "A human-readable description of what went wrong.",
    "details": [],
    "doc_url": "https://synaptiqintel.com/docs/api-reference/..."
  }
}

| Field | Type | Description | |-----------|--------|---------------------------------------------------------------| | code | string | A machine-readable error code. | | message | string | A human-readable explanation of the error. | | details | array | Optional. An array of specific validation errors. | | doc_url | string | A link to the relevant documentation page. |

HTTP Status Codes

Success Codes

| Code | Status | Description | |------|-------------|------------------------------------------------------| | 200 | OK | The request succeeded. Response body contains data. | | 201 | Created | A new resource was created successfully. | | 204 | No Content | The request succeeded with no response body (deletes).|

Client Error Codes

| Code | Status | Error Code | Description | |------|---------------------|-----------------------|----------------------------------------------------------------------| | 400 | Bad Request | invalid_request | The request body is malformed or missing required fields. | | 401 | Unauthorized | unauthorized | No API key provided, or the key is invalid or expired. | | 403 | Forbidden | forbidden | The API key does not have the required scope for this operation. | | 404 | Not Found | not_found | The requested resource does not exist. | | 409 | Conflict | conflict | The request conflicts with existing data (e.g., duplicate email). | | 422 | Unprocessable Entity| unprocessable | The request is valid JSON but fails semantic validation. | | 429 | Too Many Requests | rate_limit_exceeded | Rate limit exceeded. Check X-RateLimit-RetryAfter header. |

Server Error Codes

| Code | Status | Error Code | Description | |------|-----------------------|---------------------|--------------------------------------------------------------| | 500 | Internal Server Error | internal_error | An unexpected error on our end. Please retry with backoff. | | 502 | Bad Gateway | bad_gateway | A downstream service is temporarily unavailable. | | 503 | Service Unavailable | service_unavailable| The API is temporarily down for maintenance. | | 504 | Gateway Timeout | gateway_timeout | The request timed out. Try again with a smaller payload. |

Validation Error Details

For 400 and 422 errors, the details array provides field-level information:

{
  "error": {
    "code": "invalid_request",
    "message": "Validation failed. Check the details array for specific errors.",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "The email address 'not-an-email' is not a valid email format."
      },
      {
        "field": "phone",
        "code": "invalid_format",
        "message": "Phone number must be in E.164 format (e.g., +15551234567)."
      }
    ],
    "doc_url": "https://synaptiqintel.com/docs/api-reference/leads-api"
  }
}

Common Validation Codes

| Validation Code | Description | |--------------------|------------------------------------------------------| | required | A required field is missing. | | invalid_format | The field value does not match the expected format. | | too_long | The string exceeds the maximum allowed length. | | too_short | The string is shorter than the minimum required. | | out_of_range | A numeric value is outside the allowed range. | | invalid_enum | The value is not one of the allowed options. |

Status Page

Monitor the health of the Synaptiq API in real time at synaptiqintel.com/status. Subscribe to receive notifications for incidents and scheduled maintenance.