API errors

Nash API errors include a machine-readable code and a human-readable message. Use the code in your app, and use the message for context. Every response also includes an X-REQUEST-ID header. REST errors repeat that value in the response body as RequestID. This page covers the codes returned most often across the Platform and Fleet APIs. An endpoint may also return a code specific to its resource or operation.

REST error response

REST errors use this envelope:

{
  "error": {
    "code": "VALIDATION_ERRORS",
    "message": "Field 'pickupPhoneNumber': Input should be a valid string (type: string_type)",
    "details": {
      "fields": [
        {
          "loc": ["pickupPhoneNumber"],
          "msg": "Input should be a valid string",
          "type": "string_type"
        }
      ]
    }
  },
  "response_status": "422 UNPROCESSABLE_ENTITY",
  "RequestID": "req_example"
}

Field	How to use it
`error.code`	Stable, machine-readable identifier. Branch on this value instead of parsing the message.
`error.message`	Human-readable description. It can include context about the request and may change without changing the code.
`error.details`	Optional structured context, such as the field or item that failed.
`response_status`	HTTP status repeated in the response body.
`RequestID`	Identifier Nash support uses to trace the request. Log it with the failure.

error.details is omitted when the error has no public structured context.

HTTP statuses and retries

HTTP status	What it means	Recommended handling
`400 Bad Request`	The request is missing data, contains an invalid value, or asks for an action that is not allowed.	Correct the request before retrying.
`401 Unauthorized`	Authentication is missing, invalid, or expired.	Refresh or replace the credential, then retry.
`403 Forbidden`	The credential is valid but cannot access the resource or action.	Check the organization and API-key permissions.
`404 Not Found`	The resource does not exist in the selected environment and organization, or is not visible to the caller.	Check the ID, environment, and `Nash-Org-Id`.
`409 Conflict`	The request conflicts with an existing resource, a concurrent write, or the resource’s current state.	Retry lock or contention errors with backoff. Resolve other conflicts before retrying.
`410 Gone`	A time-limited resource, such as a tracking link, has expired.	Request or use a current resource.
`422 Unprocessable Entity`	The JSON is readable, but one or more fields or business rules failed validation.	Correct the fields reported in the message or `details`.
`429 Too Many Requests`	The organization exceeded its request rate.	Retry with exponential backoff. See Rate limits and throttling.
`500 Internal Server Error`	Nash could not complete the request.	Retry an idempotent request with backoff. Log the `RequestID` and contact support if it continues.
`502`, `503`, or `504`	Nash or a downstream service is temporarily unavailable or timed out.	Retry an idempotent request with exponential backoff and jitter.

For a write that times out or returns a server error, check the resource’s current state before sending a second write. Some operations may have completed before the response failed.

Common request and access codes

Code	HTTP status	When it is returned
`BAD_REQUEST`	`400`	A required argument is missing, fields are mutually exclusive, or the request cannot be processed in its current form.
`VALIDATION_ERRORS`	`400` or `422`	Request schema validation returns `422` and usually includes `error.details.fields`. Some legacy operation-level validations return the same code with `400`.
`INVALID_VALUE`	`400`	A field is present but its value is outside the accepted set or range.
`UNAUTHORIZED`	`401`	The API key or token is missing, invalid, or expired.
`FORBIDDEN`	`403`	The caller is authenticated but lacks permission for the resource or action.
`MISSING_RESOURCE`	`404`	A referenced order, job, task, quote, dispatch strategy, or other resource cannot be found.
`NOT_FOUND`	`404`	A resource cannot be found on an endpoint using the generic typed error contract. Newer endpoints often return a resource-specific code such as `ORDER_NOT_FOUND`.
`RESOURCE_ALREADY_EXISTS`	`400`	A unique value, often an external identifier, is already assigned to another resource on a legacy endpoint.
`ALREADY_EXISTS` or `CONFLICT`	`409`	A resource or unique value already exists on an endpoint using the conflict contract.
`DISALLOWED_OPERATION`	`400`	The requested action is not permitted for the resource, commonly because the resource has already advanced in its lifecycle.
`INVALID_STATE_TRANSITION`	`409`	The action is valid in general but conflicts with the resource’s current state.
`LOCK_ACQUISITION_FAILURE`	`409`	Another request is modifying the same resource. Retry after a short backoff.
`TOO_MANY_REQUESTS`	`429`	The organization exceeded the endpoint or organization rate limit.
`INTERNAL_SERVER_ERROR`	`500`	Nash encountered an unexpected failure. The message is intentionally general; use `RequestID` when contacting support.

Older endpoints often use generic codes such as MISSING_RESOURCE. Newer endpoints use domain-prefixed codes such as ORDER_NOT_FOUND, ROUTE_NOT_FOUND, or TASK_NOT_FOUND. Clients that call both surfaces should handle both forms.

Common order codes

Code	HTTP status	When it is returned
`ORDER_NOT_FOUND`	`404`	The order ID or external ID does not resolve in the selected organization.
`ORDER_EXTERNAL_ID_REQUIRED`	`400`	An order upsert is missing `externalId`.
`ORDER_DUPLICATE_EXTERNAL_ID`	`409`	More than one order has the supplied external ID, so Nash cannot choose one safely.
`ORDER_ALREADY_DISPATCHED`	`400`	A create, upsert, archive, or route operation would change an order that has already been dispatched.
`ORDER_LOCK_CONTENTION`	`409`	Another operation currently holds the order lock. Retry after a short backoff.
`INVALID_ADDRESS`	`400`	A pickup or dropoff address is missing required parts, cannot be parsed, cannot be geocoded, or has invalid coordinates.
`INVALID_PHONE_NUMBER`	`400`	A pickup or dropoff phone number is missing where required or is not valid. Send phone numbers in E.164 format.
`INVALID_TIME_CONSTRAINT`	`400`	A pickup or dropoff window is invalid, in the past where not allowed, or ordered incorrectly.
`INVALID_TIP`	`400`	The tip value is invalid for the request.
`ORDER_VALIDATION_ERRORS_BLOCK_ELIGIBILITY`	`422`	The order has validation errors that prevent delivery-window eligibility scoring.

Common quote and dispatch codes

Code	HTTP status	When it is returned
`NO_ELIGIBLE_PROVIDERS`	`404`	No provider is eligible under the selected dispatch strategy, contract, service area, or order requirements.
`NO_VALID_QUOTES`	`404`	Nash requested or evaluated quotes, but none remained valid for selection. Quotes may be unavailable, expired, higher than configured fee limits, or outside the allowed provider set.
`AUTODISPATCH_FAILURE`	`400`	Automatic dispatch could not select and dispatch a valid quote. The message usually includes the underlying reason.
`INVALID_OPTIONS_GROUP`	`400`	The referenced dispatch strategy is missing, inactive, or invalid for the operation. Some older API responses call a dispatch strategy an `options_group`.
`INVALID_OPTIONS_GROUP_SETTING`	`400`	A setting on the dispatch strategy is invalid or incompatible with the request.
`NO_ELIGIBLE_ROUTES`	`422`	Route optimization cannot build a route that satisfies the supplied orders and constraints.

Common route codes

Code	HTTP status	When it is returned
`ROUTE_NOT_FOUND`	`404`	The route ID does not resolve in the selected organization.
`ROUTE_ALREADY_DISPATCHED`	`400`	An update is attempted on a route that has already been dispatched.
`ROUTE_DELETED`	`400`	The action targets a deleted route.
`ROUTE_ARCHIVED`	`400`	The action targets an archived route.
`ROUTE_HAS_NO_STOPS`	`400`	The route cannot be processed or dispatched because it has no stops.
`ROUTE_HAS_NO_PACKAGES`	`400`	The route cannot be processed or dispatched because it has no packages.
`ROUTE_ACTION_INVALID_STATUS`	`400`	The requested route action is not available from the route’s current status.
`ROUTE_STOP_NOT_FOUND`	`404`	The referenced stop does not belong to the route or cannot be found.

Common Fleet API codes

Code	HTTP status	When it is returned
`DELIVERY_NOT_FOUND`	`404`	The delivery ID or package external ID does not resolve for the fleet organization.
`TASK_NOT_FOUND`	`404`	The delivery task cannot be found.
`TASK_FORBIDDEN`	`403`	The task is not owned by the selected organization.
`TASK_MISSING_TIME_WINDOW`	`422`	The task is missing a required pickup or dropoff time-window field.
`PICKUP_NOT_IN_SCOPE`	`400`	The pickup store is outside the caller’s assigned store-location scope.
`STORE_LOCATION_NOT_FOUND`	`404`	The referenced store location cannot be found in the organization.

Bulk and asynchronous operations

Some bulk endpoints return HTTP 200 or 202 while individual items fail. Inspect the documented per-item result fields, such as success, errorCode, and errorMessage, instead of relying only on the overall HTTP status. For asynchronous operations, the initial response confirms that Nash accepted the request. Retrieve the operation result to determine whether each item succeeded.

Contact support

If a server error continues after a retry, send support@usenash.com:

The RequestID
The endpoint and HTTP method
The approximate request time and environment
The error code and HTTP status

Do not send API keys, bearer tokens, or other credentials.

Getting started

Core concepts

Guides

Your fleet

Resources

REST error response

HTTP statuses and retries

Common request and access codes

Common order codes

Common quote and dispatch codes

Common route codes

Common Fleet API codes

Bulk and asynchronous operations

Contact support

​REST error response

​HTTP statuses and retries

​Common request and access codes

​Common order codes

​Common quote and dispatch codes

​Common route codes

​Common Fleet API codes

​Bulk and asynchronous operations

​Contact support

REST error response

HTTP statuses and retries

Common request and access codes

Common order codes

Common quote and dispatch codes

Common route codes

Common Fleet API codes

Bulk and asynchronous operations

Contact support