Outcomes and errors
Warehouse operations preserve current authority, complete effects, opaque cursors, and read-only unknown observation.
Complete effects
A confirmed receipt means the operation’s complete required effect set was
verified. A rejected result means no effect was accepted. A current source,
eligibility check, or guarantee that cannot be established makes the operation
unavailable. Import submissions bind the exact selected groups and revisions;
excluded groups are not submitted.
An unknown provider outcome is not permission to repeat a mutation with
the same or a new key. Retain the returned operationId and use the supported
read-only operation outcome route while your current permission
still allows it. Do not use retry, compensation, or a second overlapping
submission to infer success.
Errors and scope
HTTP errors use one JSON envelope with error.code, error.message, and
meta.requestId; validation errors may include error.fields.
An error about a warehouse write that Vault recorded can carry that write’s ID
in error.operationId. provider_outcome_unknown carries it for read-only
observation. A refusal from the warehouse system, such as validation_error,
state_conflict or rate_limited, also carries it, both the first time and
when you repeat the same submission key. That ID identifies the refused write
for support; repeating the key returns the same refusal. MCP reports the same
code and operationId in its tool error. When HTTP would send
Retry-After, the MCP tool result carries the same delay in
_meta.retryAfterSeconds. The generated reference owns the
current code vocabulary and schemas.
Missing or inaccessible customer data may return not_found without revealing
whether another organization owns it. unauthenticated and forbidden reflect
the caller’s current credentials and grants, not the credentials or grants that
were present when an earlier receipt was created.
Use the error code and message to choose the next step. A refusal caused by input or the current business state is different from a service failure. A 5xx means that the same request can succeed later. A 4xx means that the same request fails again until you or the warehouse change the input, the setup or the record. These are the existing ordinary Warehouse HTTP codes.
| HTTP | Code | Next step |
|---|---|---|
| 400 | validation_error |
Correct the request and any listed fields. PO imports currently accept one selected group per submission. |
| 401 | unauthenticated |
Supply valid credentials. |
| 403 | forbidden |
Check the current caller’s permission for this operation. |
| 404 | not_found |
Check the resource identifier and current organization access. |
| 409 | state_conflict |
Read the current state and review the operation again. This includes a record that the warehouse system no longer has or refuses for its current state. |
| 409 | warehouse_not_ready |
Follow the stated readiness instruction or contact the warehouse. Repeating the request does not complete setup or enable an unavailable capability. This includes a missing binding, a missing billing configuration, a billing environment that does not match, and a ship-from warehouse whose address changed after staff confirmed it. In that last case, order preview and shipping quotes return this code until warehouse staff confirm the warehouse again. Order creation also returns this code. A ship-from warehouse that was deleted in ShipStation is treated the same way as a changed address. A change to only the contact name, company, phone, or email does not stop orders. |
| 429 | rate_limited |
Honor Retry-After when supplied. Recheck whether the operation is safe to attempt again. |
| 500 | internal_error |
Retain the request ID and contact support. |
| 502 | provider_data_invalid |
The required warehouse response could not be verified. Retain the request ID; do not assume a write succeeded or repeat an uncertain write. |
| 503 | provider_unavailable |
A required service is temporarily unavailable. Honor any Retry-After guidance and check a write’s outcome before another submission. |
| 503 | provider_outcome_unknown |
Keep error.operationId when present and use read-only outcome observation. |
Retry-After is a delay in seconds when Vault has validated timing advice for
a rate limit or temporary unavailability. It does not authorize replaying a
write. An uncertain write does not receive retry guidance merely because its
response is 503. X-Vault-Request-ID and meta.requestId identify the request
for support. Each MCP tool result, success or error, carries its request ID in
_meta.requestId. Internal exceptions and provider details stay private.
Order cancellation that is not yet available returns warehouse_not_ready
(409), with no cancellation or new submission recorded.
The same code covers a purchase order whose linked correction is not yet
available, a provider-held document that cannot be downloaded here, and a
customer setup change that first needs a billing association. Follow the
message’s setup or access instruction. An operation deliberately restricted
in the customer sandbox returns forbidden (403).
Registered protocol credentials
An unknown or revoked protocol credential is refused with
INVALID_WAREHOUSE_SIGNATURE (401). A credential-source outage is
WAREHOUSE_UNAVAILABLE (503) with Retry-After: 30 only for a separately
admitted external read client. For a registered client without that separate
admission, an unavailable or unresolved credential source remains
INVALID_WAREHOUSE_SIGNATURE (401). Neither response establishes an external
effect or authorizes a retry of a mutation.
Vault checks the signed request timestamp only after the credential and the
signature verify. If the signature is valid but the timestamp is more than 60
seconds before or after Vault’s time, the request is refused with
WAREHOUSE_CLOCK_SKEW (401). This applies to reads, mutations and MCP setup.
An unknown, revoked or refused credential, or a bad signature, stays
INVALID_WAREHOUSE_SIGNATURE (401) and says nothing about your clock. To
recover from clock skew, synchronize the client clock, then sign the request
again with a new timestamp and nonce.
Protocol retry rule
A protocol WAREHOUSE_UNAVAILABLE (503) means an unchanged retry can succeed,
for example after a reader outage or while the referenced slot is not yet
finalized. A deterministic refusal is a 4xx, has no Retry-After, and is
terminal for the same signed request:
| HTTP | Code | Cause | Next step |
|---|---|---|---|
| 400 | INVALID_WAREHOUSE_REQUEST |
GET /v1/events rejected the query. The body carries a fields list; each code names the rule that failed. |
Follow Event feed rejections. |
| 400 | INVALID_WAREHOUSE_REQUEST |
Commit evidence has no transaction signature, or release evidence has none and finalized history cannot supply the cancellation transaction. | Send corrected evidence with a fresh idempotency key. |
| 400 | INVALID_RESERVATION_REQUEST |
A reservation create request is malformed JSON or does not match the request schema. This includes a commit deadline that is not a positive whole number, such as 0, the wrong number of input assets for the conversion, and a repeated input asset ID. Other protocol operations report a malformed request as INVALID_WAREHOUSE_REQUEST. |
Correct the request body, then sign and send it again. |
| 400 | INVALID_COMMIT_DEADLINE |
A reservation create request has a commit deadline at or before Vault’s current time, or more than 30 minutes after it. A deadline exactly 30 minutes ahead is accepted. A deadline that passes while Vault writes the reservation is also refused. | Choose a deadline within the next 30 minutes, then sign and send the request again. |
| 401 | INVALID_WAREHOUSE_SIGNATURE |
The protocol credential or its deployment binding is revoked or unverified, including on inventory and event reads. | See Registered protocol credentials. |
| 401 | WAREHOUSE_CLOCK_SKEW |
The credential and signature are valid, but the signed timestamp is more than 60 seconds from Vault’s time. | Synchronize the client clock, then sign again with a new timestamp and nonce. |
| 403 | DEPLOYMENT_MISMATCH |
An authenticated reservation create request names a deployment other than the one bound to your credential. No reservation or inventory hold is made. | Send the request for the deployment your credential is bound to. |
| 404 | RESERVATION_NOT_FOUND / MANIFEST_NOT_FOUND |
The referenced record does not exist for this deployment. | Check the identifier and the deployment. |
| 409 | FINALIZED_EVIDENCE_UNVERIFIED |
The evidence names another conversion, deployment or reservation digest, commit evidence is not in the committed state, or every reader agrees without an error that finalized chain state contradicts the evidence. On commit, it also covers Mainnet input tokens that were already burned or minted, that have no input custodian, or whose custody every reader contradicts. |
Read the reservation or the event feed, then send corrected evidence with a fresh idempotency key. |
| 409 | REVERSAL_INVENTORY_UNAVAILABLE |
The reservation cannot be reversed with the current inventory, on commit as on release. | Read the reservation or the event feed before you send another request. |
| 409 | WAREHOUSE_STATE_CONFLICT |
The current warehouse state forbids the requested transition. | Read the reservation or the event feed before you send another request. |
After a 4xx, stop retrying the same request and follow the row’s next step.
Inventory read deadline
A protocol inventory read waits at most 10 seconds for the warehouse stock
source. If the source does not answer in that time, the read returns the same
WAREHOUSE_UNAVAILABLE (503) response, with Retry-After, that it returns for
any other failed stock read. The response status and body shape do not change. The read changes no state, so an unchanged
retry is safe.
Cursors and exports
List cursors are opaque. Pass nextCursor unchanged while paging; a page may
contain fewer rows than the requested limit and still have another page.
Exports return the complete authorized bounded CSV or fail instead of silently
truncating. An empty authorized export is a header-only file. The
examples cover both forms.
The opening revisions feed uses its cursor as a durable consumer checkpoint. After a revision has been emitted, an exhausted or empty poll retains that cursor so the consumer can resume when another opening or correction is recorded. The consumer advances its checkpoint only after its own ingestion succeeds. Reading the feed does not mutate stock or openings.
Event feed rejections
GET /v1/events accepts one optional query parameter, cursor. A 400 from
this endpoint has the code INVALID_WAREHOUSE_REQUEST and a fields list.
Each field has a code, a fixed message, and a path. For
unknown_parameter, path is the name of the extra parameter. For every other
code, path is cursor. The same body is returned in the /mcp tool error.
| Reason code | Meaning |
|---|---|
unknown_parameter |
The query has a parameter other than cursor. There is one field for each extra parameter. |
empty_cursor |
The query has cursor= with no value. |
malformed_cursor |
The cursor is not in the form it was returned in. |
cursor_signature_invalid |
The cursor was changed, or it was not issued by Vault. |
cursor_payload_invalid |
The cursor has a valid signature but its content does not decode. |
cursor_binding_mismatch |
The cursor was issued for another deployment. |
cursor_stream_mismatch |
The cursor belongs to another feed, for example a manifest list cursor. |
The same request fails the same way each time. Do not retry it unchanged. To recover:
- Delete the saved checkpoint.
- Read the feed again with no
cursorparameter, and remove any other query parameter. - Save the exact
cursorfield from each response, and send it back unchanged. Do not edit, trim, or re-encode it.