Rate Limits & Error Handling

Stay within platform limits and design integrations that degrade gracefully. NidFul’s policies are built for enterprise reliability with elasticity for regional network conditions.

Global Limits

| Resource | Limit | | --- | --- | | Authenticated requests | 120 requests per minute per token | | Webhook retries | 10 attempts over ~30 minutes | | Attachment uploads | 100 MB per file |

Burst traffic can exceed these limits briefly, but sustained overages trigger throttling.

Response Codes

• 429 Too Many Requests – Rate limit exceeded.
• 400 Bad Request – Validation error; payload structure incorrect.
• 401 Unauthorized – Token expired or missing.
• 403 Forbidden – Scope insufficient for the requested action.
• 422 Unprocessable Entity – State transition invalid (e.g., closing a submission without resolution summary).
• 503 Service Unavailable – Scheduled maintenance or incident; retry with backoff.

Handling 429s

• Inspect the Retry-After header for the number of seconds to wait.
• Implement exponential backoff capped at 60 seconds.
• Spread high-volume jobs over multiple workers with distinct tokens.

async function withRetry(requestFn, retries = 5) {
  for (let attempt = 0; attempt < retries; attempt += 1) {
    const response = await requestFn();

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

    const retryAfter = Number(response.headers.get('Retry-After') ?? '5');
    await new Promise((resolve) =>
      setTimeout(resolve, (attempt + 1) * retryAfter * 1000),
    );
  }

  throw new Error('Exceeded retry attempts due to rate limiting');
}

Network Considerations

• NidFul edges requests across Lagos, Nairobi, Johannesburg, and Frankfurt. Choose the closest region when configuring integrations.
• Use persistent connections (HTTP/2) to reduce handshake overhead.
• Implement automatic retries for transient network failures common in cross-border links.

Error Visibility

• Monitor rate-limit metrics in the Integrations → API Usage dashboard.
• Subscribe to platform status updates for planned maintenance windows.
• Enable alerting in your observability stack when 4XX/5XX rates spike.

Respecting these limits keeps your integration reliable and ensures fair access for the rest of the community. Continue with Webhooks & Automation to stay updated in real time.