Skip to main content
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) 
{
  "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) 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404
}
Server Error (500) 
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request",
  "status": 500
}

​
HTTP status codes

CodeNameMeaning
200OKRequest succeeded
201CreatedResource created
204No ContentSuccess, no body (DELETE, some PUTs)
400Bad RequestValidation failed — check the errors object
401UnauthorizedMissing or expired token / API key
403ForbiddenValid token but insufficient permissions
404Not FoundResource does not exist or does not belong to your org
409ConflictDuplicate resource (e.g. CustomerNumber already exists)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected 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 
{
  "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.