Errors

The ingest API returns errors as RFC 7807 application/problem+json:

{
  "type":   "https://docs.flexgalaxy.ai/dev/wms/errors.html#cross-warehouse-credential",
  "title":  "Credential not authorized for this warehouse",
  "status": 403,
  "detail": "Credential 'ACME-TENANT-A' attempted to push for warehouse 'WH-Newark-03'.",
  "instance": "/wms-ingest/v1/inventory/movements",
  "trace_id": "01J7Y6K1NQ3W2C0X4V0R5T6E7N"
}

trace_id is propagated via W3C traceparent header. Include it in every support request.

Request-level status table

Status

Meaning

Caller action

400 Bad Request

Malformed request — invalid JSON, missing required envelope field, unknown enum value.

Fix the request shape. Do not retry as-is.

401 Unauthorized

Missing or invalid credential — cert not in registry, expired API key, bad HMAC.

Check certificate, key rotation, environment config.

403 Forbidden

Credential valid but not authorized for this resource or warehouse.

Check partner-registry warehouse scoping; do not bypass with a more-privileged credential.

404 Not Found

Job / mapping / quarantine / cursor not found.

Verify the identifier; treat as terminal — do not retry.

409 Conflict

State conflict — e.g. submitting a full-refresh while a bulk job is in-flight.

Inspect the conflicting state before retrying.

422 Unprocessable Entity

Schema-valid but the request envelope is business-invalid. Per-item business issues use QUARANTINED instead.

Fix the request envelope (e.g. wrong partner_id format).

429 Too Many Requests

Rate limited.

Honor Retry-After. Back off exponentially.

500 Internal Server Error

Platform-side failure.

Retry with exponential backoff. Open a support ticket including trace_id if persistent.

503 Service Unavailable

Receiving side is in maintenance or temporarily offline.

Retry with exponential backoff. Honor Retry-After if present.

Per-item statuses (within 200 OK responses)

A batch endpoint returns 200 OK for the request itself and reports per-item outcomes in the response body:

Item status

Meaning

ACCEPTED

Item normalized and stored. internal_id returned.

REPLAY

Item already at the submitted source_version. No mutation.

QUARANTINED

Schema valid; business validation failed. Held in the quarantine queue.

REJECTED

Item-level schema invalid (e.g. negative quantity on a SKU upsert).

The HTTP status is 200 because the batch was processed; per-item statuses report the actual outcome of each item. See Normalization and quarantine for the full semantics.

Per-item rejection vs request-level 400

Where the line falls:

  • Request-level 400 — the request envelope itself is malformed. JSON parse failure; missing top-level partner_id; unknown endpoint path; unknown mode value. No items are processed.

  • Per-item REJECTED — the request envelope is well-formed, but a specific item inside it failed item-level schema validation. Other items in the batch still process normally.

When in doubt, look at the response body. A 400 has no per-item results. A 200 with per-item rejections has them in results[*].status.

Retry strategy

Status class

Retry?

Strategy

2xx

n/a

Check per-item statuses for partial failure.

4xx except 429

No.

Fix the input; resubmit with a fresh correlation_id only if the original was logically wrong.

429

Yes

Honor Retry-After.

5xx

Yes

Exponential backoff. Same correlation_id to leverage request-level idempotency.

Retrying a 4xx (other than 429) wastes resources on both sides. The server will not change its answer on retry of the same (partner_id, correlation_id).

Async job errors

Bulk jobs report errors via the errors_url returned alongside state: COMPLETED_WITH_ERRORS:

GET /wms-ingest/v1/jobs/job-01HZ.../errors?page_token=...

{
  "items": [
    { "source_id": "SKU-FOO-001", "status": "QUARANTINED", "reason": "Unknown UoM 'KG'." },
    { "source_id": "SKU-BAR-002", "status": "REJECTED",    "reason": "Negative qty in initial stock." }
  ],
  "next_page_token": "...",
  "has_more": true
}

Paginate until has_more = false. Errors persist for 30 days after job completion (see Sync modes — bulk).