Error Handling

The NRS API uses standard HTTP status codes to indicate the success or failure of a request.

All error responses are returned in JSON format.

---

HTTP Status Codes

Status Code	Meaning
200	Request completed successfully
400	Invalid request or upstream validation failure
401	Unauthorized request
404	Resource not found
409	Resource conflict
422	Request validation error
429	Too many requests
500	Internal server or proxy failure

---

Standard Error Response

Most failed requests return the following structure:

{
  "endpoint": "string",
  "status_code": 0,
  "ok": false,
  "error": "string"
}

---

Validation Errors

Validation failures return a detailed list of field-level issues.

{
  "detail": [
    {
      "loc": [
        "body",
        "invoice_number"
      ],
      "msg": "Field required",
      "type": "missing",
      "input": null,
      "ctx": {}
    }
  ]
}

---

Common Error Scenarios

400 — Bad Request

Returned when:

• Required fields are missing
• Payload structure is invalid
• Upstream eTranzact validation fails
• Invalid IRN values are supplied

Example:

{
  "endpoint": "/api/v1/nrs/transmit",
  "status_code": 400,
  "ok": false,
  "error": "Invalid IRN supplied"
}

---

401 — Unauthorized

Returned when:

• API credentials are missing
• Authentication tokens are invalid
• Access is denied

Example:

{
  "ok": false,
  "error": "Unauthorized"
}

---

409 — Conflict

Returned when:

• A QR code already exists for the supplied IRN
• Duplicate resources are detected

Example:

{
  "ok": false,
  "error": "QR code already exists for this IRN"
}

---

422 — Validation Error

Returned when request payload validation fails.

Example:

{
  "detail": [
    {
      "loc": ["body", "issue_date"],
      "msg": "Invalid date format",
      "type": "value_error"
    }
  ]
}

---

429 — Too Many Requests

Returned when the API rate limit has been exceeded.

Example:

{
  "ok": false,
  "error": "Rate limit exceeded"
}

---

500 — Internal Server Error

Returned when:

• Local proxy processing fails
• Encryption or QR generation fails
• Upstream services are unavailable

Example:

{
  "endpoint": "/api/v1/nrs/qrcode",
  "status_code": 500,
  "ok": false,
  "error": "Local QR generation failure"
}

---

Best Practices

• Always validate request payloads before submission.
• Handle 429 responses with retry logic.
• Log upstream errors for troubleshooting.
• Ensure all date fields use the YYYY-MM-DD format.
• Ensure time fields use the HH:MM:SS format.
• Retry transient 500 errors using exponential backoff.