Rate Limiting

The Space Invoices API enforces rate limits to ensure fair usage and protect service stability. When you exceed a rate limit, the API returns a 429 Too Many Requests response.

How It Works

Rate limits are applied per IP address on a per-minute sliding window. Authentication endpoints have stricter limits to prevent abuse.

If a request is rate limited, the response includes a Retry-After header indicating how many seconds to wait before retrying.

429 Response

When the rate limit is exceeded:

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded"
}

Headers:

Header	Description
Retry-After	Seconds to wait before making another request

Handling Rate Limits

Handling curlbash

Copy

# title: Handling 429 responses
# Check for rate limit headers
curl -i "https://eu.spaceinvoices.com/v1/entities/ent_123/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response headers include:
# Retry-After: 60
#
# If you receive HTTP 429, wait for the Retry-After duration before retrying.

Retry with Exponential Backoff

The recommended approach is to catch 429 responses and wait for the Retry-After duration:

Retry sdktypescript

Copy

// title: Retry with backoff
async function withRetry(fn: () => Promise, maxRetries = 3): Promise {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch(error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = Number(error.headers?.["retry-after"]) || 60;
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const _invoices = await withRetry(() => sdk.invoices.getInvoices());

Best Practices

• Respect Retry-After — always wait the indicated duration before retrying
• Batch operations — combine multiple items into a single request where the API supports it (e.g., bulk endpoints)
• Cache responses — avoid re-fetching data that hasn’t changed
• Use webhooks — instead of polling for changes, register webhooks to receive push notifications
• Paginate efficiently — request only the data you need using appropriate limit values

Email Rate Limits

Email sending endpoints have separate, per-document rate limits to prevent abuse. If you exceed the email sending limit for a specific document, wait before retrying.