Namirial Notify APIs do not all expose the same error payload shape. When building a production integration, handle errors in two layers:
- First, branch on the HTTP status code.
- Then, parse the service-specific error body when one is available.
Use this guide as the shared reference for error behavior across these APIs.
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/Query, EviPost Submit, Query, Cancel and 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, Query, Cancel and AffidavitRequest; EviMail Submit; EviNotice Submit, Query, affidavit downloads and AffidavitRequest |
404 Not Found | The requested resource was not found. | EviNotice Get, attachments ZIP, single affidavit and AffidavitRequest (affidavits ZIP uses 403); EviPost Cancel |
405 Method Not Allowed | Requested functionality is disabled or unsupported for this notice. | EviNotice Submit and AffidavitRequest |
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 |
492 | The submission quota for this recipient or for this service type on your site was reached. Avoid retrying immediately; contact support if it persists. | EviPost Submit |
See the operation list above for 403. 409 applies to all Submit endpoints when idempotency is in use — see 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.
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.
Single-message EviMail operations use the v1 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 |
Parse responseStatus for v1 EviMail service errors. The v2 EviMail batch operations can return Problem Details responses. For example, recipient CSV validation returns HTTP 400 with a problem description. See the EviMail batch API.
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 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.
EviSign’s v1 issuer operations return errors with a camelCase responseStatus envelope. Use the EviSign API error table for operation-specific status codes. For Cancel and Resend, a 401 can also indicate that the authenticated caller does not own the EviSign.
EviSign Bundle uses the v2 Problem Details response format. SignLink runs on the application host and has its own error format. Use its HTTP status for client branching.
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.
- 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.
- 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.
- 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.
- 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.