Errors

Every error follows the same envelope. When a field mapping is active, field names inside the error refer to your schema.

Envelope

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable summary",
    "details": [
      {"field": "field_name", "message": "Why this field failed"}
    ]
  }
}

Property	Type	Notes
success	boolean	Always false
error.code	string	Machine-readable, always UPPER_SNAKE_CASE
error.message	string	Human summary
error.details[]	array	Present for VALIDATION_ERROR

note

Auth/permission errors use Django REST Framework's native envelope — a flat {"detail": "..."} — not the format above.

Error codes

Code	HTTP	Meaning
VALIDATION_ERROR	400	One or more fields failed validation (see details[])
SERVICE_ERROR	400	Business rule violation (e.g. SKU not found, order shipped)
MAPPING_ERROR	422	Mapping engine couldn't process the payload
NOT_FOUND	404	No record matches the identifier
DUPLICATE	409	Unique constraint conflict

HTTP status summary

Status	When
200	GET / PUT / DELETE succeeded
201	POST created a record
400	Validation or business-rule error (see code)
401	Invalid or expired API key
403	No key, no partner linked, partner deactivated, or missing scope
404	Record not found
409	Duplicate unique field
422	Field mapping engine failed

Examples

VALIDATION_ERROR — 400

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields failed validation.",
    "details": [
      {"field": "order_number", "message": "This field is required."},
      {"field": "items", "message": "At least one item is required."}
    ]
  }
}

SERVICE_ERROR — 400

{
  "success": false,
  "error": {
    "code": "SERVICE_ERROR",
    "message": "SKU not found: NONEXISTENT-SKU"
  }
}

MAPPING_ERROR — 422

{
  "success": false,
  "error": {
    "code": "MAPPING_ERROR",
    "message": "Failed to map inbound payload: <reason>"
  }
}

Review the mapping in the dashboard — the source path probably doesn't exist in the payload you're sending.

NOT_FOUND — 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found: ERP-5001"
  }
}

Verify (1) the identifier value is correct, (2) the partner's identifier field matches, and (3) the record hasn't been soft-deleted.

DUPLICATE — 409

{
  "success": false,
  "error": {
    "code": "DUPLICATE",
    "message": "A location with code \"A-101\" already exists."
  }
}

What you can check before contacting support

1. The key scope covers the action you're attempting — Scopes.
2. The identifier field matches what you put in the URL.
3. All sku_codes referenced by an order exist as products.
4. Dates are ISO 8601 — see Dates & timezones.
5. The mapped payload (visible in the Integration Logs view of the dashboard) contains what you expect after transformation.

If a request still looks wrong, open a support ticket with the request's timestamp and your partner slug.