# Error Reference

Every endpoint in the NSE API uses a consistent set of HTTP status codes. This reference describes what each code means, what the response body looks like where applicable, and what you should do when you encounter it.

## HTTP Status Codes

### 400 Bad Request

The request was structurally invalid — a required field was missing, a value was the wrong type, an enum value was not recognised, or a field failed a format check (e.g. a string that was expected to be a UUID).

The response body is an `ErrorsResponse` object containing one or more error entries that identify exactly which field or rule caused the rejection.

**What to do:** Read the error details in the response body. Fix the request payload before retrying. Do not retry the same request without changes — it will fail again.

Common causes:

- A required field is absent (e.g. no `type` on a stage)
- An enum value is wrong case or misspelled (e.g. `"signer"` instead of `"Signer"`)
- A UUID field contains a value that is not a valid UUID
- A date-time field is not in ISO 8601 format


### 401 Unauthorized

The request did not include a valid Bearer token, or the token has expired.

**What to do:** Obtain a fresh JWT token and retry the request with the updated `Authorization: Bearer {token}` header. Do not retry with the same token if it has expired.

### 403 Forbidden

The token is valid but the authenticated user does not have permission to perform this operation. This typically means the user does not have the required role or does not belong to the organization specified in the path.

**What to do:** Verify that the `organizationId` in the request path matches the organization the user belongs to, and that the user has the necessary permissions. This is not a transient error — retrying will not help.

### 404 Not Found

The resource referenced in the path does not exist. This applies to envelopes, stages, recipients, files, and artifacts.

**What to do:** Check that the IDs in the request path are correct and that the resource was created successfully before this call. A `404` on a recently created resource may indicate that a previous creation call failed silently or that you are using the wrong ID.

### 422 Unprocessable Content

The request was structurally valid but could not be executed because of a business rule violation. The entity exists and the request is well-formed, but the operation is not permitted in the current state.

The response body is an `ErrorsResponse` object with details about which rule was violated.

**What to do:** Read the error details. The fix depends on the specific rule — common scenarios include:

- Attempting to modify an envelope that has already been sent
- Attempting to send an envelope that has no recipients or no files
- Placing a field task for a `recipientId` that does not belong to the envelope
- Attempting to create a resource on an envelope that is not in `draft` status


### 500 Internal Server Error

An unexpected error occurred on the server side. This is not caused by the request content.

**What to do:** Retry the request after a brief delay. If the error persists, it indicates a platform issue. Contact Namirial support with the request details and timestamp so the incident can be investigated.

## The ErrorsResponse Body

Error responses include a structured error body. The schema is named `ErrorsResponse` and contains a list of error entries describing what went wrong.

> Note: The exact field names of the ErrorsResponse schema are not confirmed from the current API specification. Inspect the actual response body in your integration to determine the precise structure. The body will always be JSON.


## Quick Reference Table

| Code | Name | Fix required |
|  --- | --- | --- |
| 400 | Bad Request | Fix the request payload |
| 401 | Unauthorized | Refresh the Bearer token |
| 403 | Forbidden | Check organization ID and user permissions |
| 404 | Not Found | Verify the resource ID exists |
| 422 | Unprocessable Content | Fix the business rule violation |
| 429 | Too Many Requests | Implement backoff, reduce call frequency |
| 500 | Internal Server Error | Retry; contact support if persistent |