Passer au contenu

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.

StatusMeaning in the current docsWhere it appears
200 OKThe request was accepted or the resource was returned successfully.All documented APIs
202 AcceptedAn idempotent replay returned the cached body of a previous 200 OK Submit request.EviMail Submit, EviSMS Submit, EviNotice Submit, EviPost Submit
204 No ContentThe endpoint is valid, but there is no downloadable content yet.EviNotice attachment and affidavit downloads
400 Bad RequestThe 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 UnauthorizedAuthentication failed.All documented APIs
403 ForbiddenThe 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 FoundThe requested resource was not found.EviNotice Get, attachments ZIP, single affidavit and AffidavitRequest (affidavits ZIP uses 403); EviPost Cancel
405 Method Not AllowedRequested functionality is disabled or unsupported for this notice.EviNotice Submit and AffidavitRequest
409 ConflictA 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
492The 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.


Error body formats by service

EviNotice

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

FieldMeaning
StatusHTTP status code
TypeURI identifying the problem type
TitleShort summary of the error
DetailHuman-readable explanation
InstanceURI reference identifying the specific occurrence of the problem. May be absent.
RequestIdRequest identifier for support and troubleshooting
InvalidValuesArray 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

Single-message EviMail operations use the v1 service-style error payload:

FieldMeaning
responseStatus.errorCodeService-specific error code
responseStatus.messageMain error message
responseStatus.errorsOptional 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.

EviSMS

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

FieldMeaning
responseStatus.errorCodeService-specific error code
responseStatus.messageMain error message
responseStatus.errorsOptional 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:

FieldMeaning
responseStatus.errorCodeService-specific error code
responseStatus.messageMain error message
responseStatus.errorsOptional array of field-level or validation details

Parse responseStatus for all EviPost error responses.


EviSign

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.


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-IdempotencyStatusHTTP statusMeaning
New200 OKFirst time this token is seen. The request executed normally.
Replay202 AcceptedThe token matched a cached 200 OK submission. The original response body is returned. The message is not resubmitted.
Conflict409 ConflictAnother 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.


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.