> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Nymble Commerce API Error Codes, Formats & Troubleshooting
> Reference for all Nymble Commerce API HTTP status codes, structured error response formats, and troubleshooting steps for common API issues.
Nymble Commerce returns standard HTTP status codes and structured error bodies. This page covers what each code means and how to resolve common errors.
## Error response format
All Nymble Commerce errors return JSON. The shape of the body depends on the error type.
**Validation error (400)**
```json theme={null}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred",
"status": 400,
"errors": {
"FieldName": ["Error message"]
}
}
```
**Not Found (404)**
```json theme={null}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "Not Found",
"status": 404
}
```
**Server Error (500)**
```json theme={null}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
"title": "An error occurred while processing your request",
"status": 500
}
```
***
## HTTP status codes
| Code | Name | Meaning |
| ---- | --------------------- | ------------------------------------------------------- |
| 200 | OK | Request succeeded |
| 201 | Created | Resource created |
| 204 | No Content | Success, no body (DELETE, some PUTs) |
| 400 | Bad Request | Validation failed — check the `errors` object |
| 401 | Unauthorized | Missing or expired token / API key |
| 403 | Forbidden | Valid token but insufficient permissions |
| 404 | Not Found | Resource does not exist or does not belong to your org |
| 409 | Conflict | Duplicate resource (e.g. CustomerNumber already exists) |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected error — retry with backoff |
***
## Common errors and fixes
Check that you are passing the `x-api-key` header with your access token as the value. Sending the token in an `Authorization` header or omitting the header entirely will produce a 401.
Also verify that your token has not expired. Tokens issued by the login endpoint are valid for `ExpiresIn` seconds (typically 86,400 seconds / 24 hours). Exchange your `ClientId` and `ClientSecret` for a fresh token and retry.
Your account role does not allow this action. Nymble Commerce enforces policy-based authorization across three primary roles: **Admin**, **Customer**, and **SalesRep**. Contact your org admin to review the role assigned to your account, and confirm that the role grants access to the endpoint you are calling.
A 400 at checkout almost always means a required field is missing or invalid. Check the `errors` object in the response body and verify the following:
* `ShippingDetails` is present and fully populated.
* All cart items reference valid SKUs that exist in your catalog.
* The cart is not empty.
This is usually an `OrganizationId` mismatch. Every resource in Nymble Commerce is scoped to the organization encoded in your token. If the token you used to create the resource belongs to a different org than the token you are using to fetch it, the API returns 404 as if the resource does not exist.
Ensure your token is scoped to the same org as the resource you are trying to access.
The login endpoint (`POST /api/auth/login`) is rate-limited to **10 requests per minute**. Rather than requesting a new token on every API call, cache the token in your application and reuse it until it expires. The rate limit window resets after 60 seconds.
`CustomerNumber` must be unique within your organization. If you receive a 409, a customer with that number already exists. Use `GET /api/customers/{customerNumber}` to look up the existing record, then decide whether to update it or choose a different `CustomerNumber` for the new customer.
Document CDN URLs are signed and expire after **1 hour**. If you stored a `cdnUrl` from an earlier response and are accessing it more than an hour later, the URL will return 403. Call `POST /api/companydocs/documents/{documentId}/refresh-url` to generate a new signed URL before serving the document to your users.
***
## Validation errors
When Nymble Commerce returns a 400, the response body includes an `errors` object. Each key is a field name (which may be `camelCase` or `PascalCase` depending on the endpoint). Each value is an array of one or more human-readable message strings describing what is wrong.
**Example — multi-field validation error**
```json theme={null}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred",
"status": 400,
"errors": {
"CustomerNumber": ["CustomerNumber is required"],
"CompanyName": ["CompanyName must not exceed 255 characters"],
"CompanyEmail": ["CompanyEmail is not a valid email address"]
}
}
```
Iterate over all keys in `errors` and surface each message to your user or log them for debugging. A single request can produce validation failures across multiple fields simultaneously.
***
## Retry guidance
For **500 Internal Server Error** responses, retry with exponential backoff — wait 1 second before the first retry, 2 seconds before the second, 4 seconds before the third. For **429 Too Many Requests**, wait until the rate limit window resets (typically 60 seconds) before retrying. Never retry a **400 Bad Request** or **404 Not Found** without first fixing the request — the same invalid request will produce the same error every time.