# Error handling

Namirial Notify APIs do not all expose the same error payload shape. When
building a production integration, handle errors in two
layers:

1. First, branch on the HTTP status code.
2. Then, parse the service-specific error body when one is available.


Use this guide as the shared reference for error behavior across these APIs.

## Common HTTP status codes

These are the response codes explicitly documented across the EviMail, EviSMS,
EviNotice, and EviPost API references.

| Status | Meaning in the current docs | Where it appears |
|  --- | --- | --- |
| `200 OK` | The request was accepted or the resource was returned successfully. | All documented APIs |
| `202 Accepted` | An idempotent replay returned the cached body of a previous `200 OK` Submit request. | EviMail Submit, EviSMS Submit, EviNotice Submit, EviPost Submit |
| `204 No Content` | The endpoint is valid, but there is no downloadable content yet. | EviNotice attachment and affidavit downloads |
| `400 Bad Request` | The request is invalid, incomplete, or fails a business rule. | EviMail Submit/AffidavitRequest, EviSMS Submit, EviNotice Submit/Get, EviPost Submit/AffidavitRequest |
| `401 Unauthorized` | Authentication failed. | All documented APIs |
| `403 Forbidden` | The authenticated account is not provisioned for the requested service, lacks required API permissions, or has attempted a disallowed operation (such as specifying a restricted `From` address or setting an internal header). | EviPost Submit and Query; EviMail Submit |
| `404 Not Found` | The requested resource was not found. | EviNotice Get and affidavit download |
| `409 Conflict` | A concurrent Submit request is already in flight with the same `X-Evi-IdempotencyToken`. Back off and retry with the same token. | EviMail Submit, EviSMS Submit, EviNotice Submit, EviPost Submit |


`403` applies to both EviPost and EviMail Submit. `409` applies to all Submit endpoints when idempotency is in use — see [Idempotency signals](#idempotency-signals) below. No single cross-service contract is defined for `429` or `5xx` responses — validate those with your Namirial Notify contact before you depend on them.

## Error body formats by service

### EviNotice

The EviNotice Submit endpoint documents an `application/problem+json` payload
with these fields:

| Field | Meaning |
|  --- | --- |
| `Status` | HTTP status code |
| `Type` | URI identifying the problem type |
| `Title` | Short summary of the error |
| `Detail` | Human-readable explanation |
| `Instance` | URI reference identifying the specific occurrence of the problem. May be absent. |
| `RequestId` | Request identifier for support and troubleshooting |
| `InvalidValues` | Array of field-level validation errors, each describing a field path and the reason it failed. Present on `400` validation errors. |


This is the most explicit error contract in this API set.

### EviMail

EviMail is a V1 service. All EviMail endpoints return the same service-style error payload:

| Field | Meaning |
|  --- | --- |
| `responseStatus.errorCode` | Service-specific error code |
| `responseStatus.message` | Main error message |
| `responseStatus.errors` | Optional array of field-level or validation details |


This applies to EviMail V1 endpoints such as `POST /v1/EviMail/Submit` and `POST /v1/EviMail/AffidavitRequest`. Parse `responseStatus` for all EviMail error responses.

### EviSMS

The EviSMS OpenAPI specification defines a legacy service-style error payload:

| Field | Meaning |
|  --- | --- |
| `responseStatus.errorCode` | Service-specific error code |
| `responseStatus.message` | Main error message |
| `responseStatus.errors` | Optional array of field-level or validation details |


### EviPost

EviPost is a V1 service and uses the same service-style error payload as EviMail and EviSMS:

| Field | Meaning |
|  --- | --- |
| `responseStatus.errorCode` | Service-specific error code |
| `responseStatus.message` | Main error message |
| `responseStatus.errors` | Optional array of field-level or validation details |


Parse `responseStatus` for all EviPost error responses.

## Idempotency signals

All four Submit endpoints support the `X-Evi-IdempotencyToken` request header. When present, the server echoes back an `X-Evi-IdempotencyStatus` response header:

| `X-Evi-IdempotencyStatus` | HTTP status | Meaning |
|  --- | --- | --- |
| `New` | `200 OK` | First time this token is seen. The request executed normally. |
| `Replay` | `202 Accepted` | The token matched a cached `200 OK` submission. The original response body is returned. The message is **not** resubmitted. |
| `Conflict` | `409 Conflict` | Another Submit with the same token is currently in flight. Back off and retry with the same token. |


Responses `400`, `401`, `408`, `429`, and `5xx` are not cached — a request that results in one of these codes re-executes regardless of the token.

## Recommended client behavior

### On `400 Bad Request`

- Treat the request as invalid until you have reviewed the payload.
- Log the endpoint, the request identifier if present, and the parsed error
fields.
- Do not blindly retry the same payload. Fix validation or business-rule issues
first.


### On `401 Unauthorized`

- Verify that you are using the right environment base URL.
- Verify that the credentials match the environment and enabled services for
your organisation.
- Fail fast and alert operations rather than retrying continuously.


### On `404 Not Found`

- Handle it as a normal integration case when retrieving a known resource.
- Confirm that you are querying with the right ID and against the right
environment.


## Production recommendations

- Parse the JSON body when present, but always preserve the raw HTTP status
code in logs and telemetry.
- Do not hard-code logic against a single error message string.
- Treat `RequestId`, `Instance`, and similar identifiers as support artifacts
worth capturing.
- Normalize the different service-specific payloads in your own client layer so
downstream systems receive a consistent internal error object.


## Related

- [API documentation](/products/namirialnotify/dev/api-documentation)
- [Integration workflows](/products/namirialnotify/dev/integration-patterns)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [EviMail API](/products/namirialnotify/apis/evimail-api)
- [EviSMS API](/products/namirialnotify/apis/evisms-api)
- [EviNotice API](/products/namirialnotify/apis/evinotice-api)
- [EviPost API](/products/namirialnotify/apis/evipost-api)