Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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:

  1. Delete the saved checkpoint.
  2. Read the feed again with no cursor parameter, and remove any other query parameter.
  3. Save the exact cursor field from each response, and send it back unchanged. Do not edit, trim, or re-encode it.

Was this page helpful?