Errors and Status Codes
Handle common errors, interpret HTTP status codes, and troubleshoot issues effectively when integrating with the Wholechain API.
Always inspect the response body for detailed error messages, even on success codes.
Common Issues and Resolutions
Use these targeted fixes for frequent problems.
{
"type": "https://tools.ietf.org/html/rfc4918#section-11.2",
"title": "Product instance not found: LotSerial: (LOT-20250723-A7), ProductId: (prod_atlantic_salmon_fillet_10lb) on location 105 before 2025-07-23 10:00:00",
"status": 422,
"traceId": "00-a5f70f30a335bf1f20afd4c79ec7c78a-d22743f3e6e0ffc0-00",
"errorDetails": [
{
"eventId": "SHIP-20250723-001",
"message": "Product instance not found: LotSerial: (LOT-20250723-A7), ProductId: (prod_atlantic_salmon_fillet_10lb) on location 105 before 2025-07-23 10:00:00"
}
]
}
The most likely reasons are:
- The lot was never received or commissioned at location 105.
There needs to be an earlier event that creates inventory for that exact product/lot at location105. - The inventory exists, but at a different location.
For example, the Receive may have put it at location104, while the Ship says it is shipping from105. - The earlier event happened after 10:00.
Event chronology matters. If the Receive is timestamped2025-07-23 11:00:00, then from Wholechain's perspective that inventory did not exist when the 10:00 Ship occurred. - The Product ID or lot code doesn't match exactly.
The earlier inventory might have:- a different product identifier,
- a slightly different lot code,
- different casing/formatting,
- or have been created against a different product record.
- The inventory was already consumed or shipped.
The lot may originally have existed at location 105, but a previous Ship or Transform may already have removed the available quantity. - The upstream event failed.
If you sent a Receive/Commission before this Ship but that event errored, then the Ship payload can be structurally correct while the underlying inventory was never created.
What to check
Look immediately before 2025-07-23 10:00:00 and find the event that is supposed to put LOT-20250723-A7 into location 105.
Status Codes
| Status | When it happens | Example message |
|---|---|---|
| 400 | Request cannot be read: missing X-API-KEY, malformed JSON, wrong field type, missing required field, invalid pagination | {"errors":{"X-API-KEY":["The apiKey field is required."]}} "PageNumber and PageSize must be greater than 0." |
| 401 | API key is not valid | "The API key is not valid." |
| 404 | Referenced product, location, event, or pending shipment does not exist | "Product not found: ", "Location not found: ", "Event not found: ", "No pending ship event found with ExternalEventId matching ShipEventId: " |
| 409 | Conflict with existing data | "Event has subsequent events and cannot be deleted.", "Product instance LotSerial: already exists.", "Event time must be greater than the previous event." |
| 413 | File too large (Documents upload); body is HTML, not JSON | — |
| 415 | Content-Type is not application/json on JSON endpoints; empty body | — |
| 422 | Business or validation rule failed — missing/insufficient inventory, invalid UnitDescriptor, duplicate event ID | "Quantity must be greater than 0", "Duplicate event id .", "EventTime is required" |
| 500 | Unexpected server error — retry later and contact support with the traceId | — |
Error Body Format
Most errors are JSON problem-details objects (RFC 9110) containing:
type— URI reference to the problem typetitle— short human-readable summarystatus— HTTP status codetraceId— correlation ID for support
Event errors also include an errorDetails array:
"errorDetails": [
{ "eventId": "SHIP-20250723-001", "message": "Product instance not found: …" }
]
400 validation errors include an errors map of field name to message array:
"errors": {
"X-API-KEY": ["The apiKey field is required."]
}
A few errors return a plain JSON string instead of a problem-details object — pagination bounds messages and some document-upload multi-file errors.
Getting Help
When contacting support, include the traceId from the error body so the team can locate your request in the logs.
Most issues stem from authentication or payload validation. Double-check headers and JSON structure first.