HTTP Status Codes

The Heirs E-Invoicing Middleware uses standard HTTP status codes. Every response also includes a success boolean and, on errors, a plain-English error message.

---

Success Codes

Code	Status	When returned
200	OK	Request succeeded — GET, PATCH, PUT, DELETE actions
201	Created	Resource successfully created — POST to create endpoints

---

Client Error Codes (4xx)

These indicate a problem with your request. Fix the issue before retrying.

Code	Status	Common cause
400	Bad Request	Malformed JSON, missing required fields, or invalid state transition
401	Unauthorized	Missing or invalid x-api-key, x-admin-key, or JWT token
403	Forbidden	Valid credentials but insufficient permissions, or tenant is suspended
404	Not Found	Tenant, user, API key, or route ID does not exist
405	Method Not Allowed	Wrong HTTP method for this endpoint
422	Unprocessable Entity	Request is structurally valid but fails business rules or schema validation
429	Too Many Requests	API rate limit exceeded for this tenant

---

Server Error Codes (5xx)

These indicate a problem on the platform side.

Code	Status	What to do
500	Internal Server Error	Retry once after a short delay. If it persists, contact support
502	Bad Gateway	Transient upstream error — retry with exponential backoff
503	Service Unavailable	Platform is under maintenance

---

Rate Limits

Rate limits are configured per tenant:

Setting	Default	Range
apiRateLimit	Platform default	10–10,000 requests per minute

When the limit is exceeded, the response is 429 with a Retry-After header (in seconds). Wait for the specified duration before retrying.

To increase your rate limit, contact your platform admin or update via PATCH /v1/tenants/{tenantId}:

{
  "limits": {
    "apiRateLimit": 1000
  }
}

---

Response Envelope Reference

Every response (success or error) wraps the result:

// Success
{
  "success": true,
  "data": { ... },
  "count": 25
}

// Error
{
  "success": false,
  "error": "Tenant not found",
  "statusCode": 404
}

Always check success before consuming data.