Understand error envelopes, standard HTTP status codes, error recovery, and rate limiting policies.

Errors & Rate Limits

The Tax Nigeria Partner API follows consistent RESTful conventions for error handling and request throttling.

Standard Error Response

When an error occurs, the API returns a descriptive JSON payload alongside the corresponding HTTP status code:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field 'annualGrossSalary' must be a positive number.",
    "details": [
      {
        "field": "annualGrossSalary",
        "issue": "Expected number >= 0, received -500000"
      }
    ]
  }
}

HTTP Status Codes

Status Code	Description	Typical Cause
`200 OK`	Request completed successfully.	Valid calculation or retrieval.
`400 Bad Request`	Input validation failed (`INVALID_INPUT`).	Malformed JSON body, negative salary, invalid tax year, or missing fields.
`401 Unauthorized`	Authentication failed (`UNAUTHORIZED`).	Missing `Authorization` header, invalid bearer token, or revoked API key.
`403 Forbidden`	Insufficient permissions (`FORBIDDEN_SCOPE`).	API key lacks the required scope (e.g., calling `/api/v1/tax/calculate` without `tax:calculate`).
`404 Not Found`	Resource not found (`NOT_FOUND`).	Unknown endpoint path or tax rule version.
`429 Too Many Requests`	Rate limit or credit exhaustion (`RATE_LIMITED` / `INSUFFICIENT_CREDITS`).	Request quota exceeded or organization out of API credits.
`500 Internal Error`	Server error (`INTERNAL_SERVER_ERROR`).	Unexpected execution failure. Contact developer support.

Rate Limits & Headers

Every API response includes HTTP headers detailing your current usage quota:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 284
X-RateLimit-Reset: 1719576000

Rate Limit Tiers

Standard / Free Tier: 60 requests per minute.
Pro / Business Tier: 300 requests per minute.
Enterprise Tier: Custom burst limits, dedicated compute, and 99.99% uptime SLA.

Handling 429 & Retry Strategy

When receiving a 429 Too Many Requests, inspect the Retry-After header or implement exponential backoff with jitter:

async function fetchWithRetry(url: string, options: RequestInit, retries = 3): Promise<Response> {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = res.headers.get("Retry-After");
    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000 + Math.random() * 200;
    
    console.warn(`Rate limited. Backing off for ${Math.round(delay)}ms...`);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error("Tax Nigeria Partner API: Exceeded maximum retry attempts due to rate limiting.");
}

Errors & Rate Limits

The Tax Nigeria Partner API follows consistent RESTful conventions for error handling and request throttling.

Standard Error Response

When an error occurs, the API returns a descriptive JSON payload alongside the corresponding HTTP status code:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field 'annualGrossSalary' must be a positive number.",
    "details": [
      {
        "field": "annualGrossSalary",
        "issue": "Expected number >= 0, received -500000"
      }
    ]
  }
}

HTTP Status Codes

Status Code	Description	Typical Cause
`200 OK`	Request completed successfully.	Valid calculation or retrieval.
`400 Bad Request`	Input validation failed (`INVALID_INPUT`).	Malformed JSON body, negative salary, invalid tax year, or missing fields.
`401 Unauthorized`	Authentication failed (`UNAUTHORIZED`).	Missing `Authorization` header, invalid bearer token, or revoked API key.
`403 Forbidden`	Insufficient permissions (`FORBIDDEN_SCOPE`).	API key lacks the required scope (e.g., calling `/api/v1/tax/calculate` without `tax:calculate`).
`404 Not Found`	Resource not found (`NOT_FOUND`).	Unknown endpoint path or tax rule version.
`429 Too Many Requests`	Rate limit or credit exhaustion (`RATE_LIMITED` / `INSUFFICIENT_CREDITS`).	Request quota exceeded or organization out of API credits.
`500 Internal Error`	Server error (`INTERNAL_SERVER_ERROR`).	Unexpected execution failure. Contact developer support.

Rate Limits & Headers

Every API response includes HTTP headers detailing your current usage quota:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 284
X-RateLimit-Reset: 1719576000

Rate Limit Tiers

Standard / Free Tier: 60 requests per minute.
Pro / Business Tier: 300 requests per minute.
Enterprise Tier: Custom burst limits, dedicated compute, and 99.99% uptime SLA.

Handling 429 & Retry Strategy

When receiving a 429 Too Many Requests, inspect the Retry-After header or implement exponential backoff with jitter:

async function fetchWithRetry(url: string, options: RequestInit, retries = 3): Promise<Response> {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = res.headers.get("Retry-After");
    const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000 + Math.random() * 200;
    
    console.warn(`Rate limited. Backing off for ${Math.round(delay)}ms...`);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error("Tax Nigeria Partner API: Exceeded maximum retry attempts due to rate limiting.");
}

Errors & Rate Limits

Errors & Rate Limits

Standard Error Response

HTTP Status Codes

Rate Limits & Headers

Rate Limit Tiers

Handling 429 & Retry Strategy

On this page

Errors & Rate Limits

Errors & Rate Limits

Standard Error Response

HTTP Status Codes

Rate Limits & Headers

Rate Limit Tiers

Handling 429 & Retry Strategy

On this page

Errors & Rate Limits

Errors & Rate LimitsCopy Anchor Link

Standard Error ResponseCopy Anchor Link

HTTP Status CodesCopy Anchor Link

Rate Limits & HeadersCopy Anchor Link

Rate Limit TiersCopy Anchor Link

Handling 429 & Retry StrategyCopy Anchor Link

On this page

Errors & Rate Limits

Errors & Rate LimitsCopy Anchor Link

Standard Error ResponseCopy Anchor Link

HTTP Status CodesCopy Anchor Link

Rate Limits & HeadersCopy Anchor Link

Rate Limit TiersCopy Anchor Link

Handling 429 & Retry StrategyCopy Anchor Link

On this page

Errors & Rate Limits

Standard Error Response

HTTP Status Codes

Rate Limits & Headers

Rate Limit Tiers

Handling 429 & Retry Strategy

Errors & Rate Limits

Standard Error Response

HTTP Status Codes

Rate Limits & Headers

Rate Limit Tiers

Handling 429 & Retry Strategy