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.