[
  {
    "code": "INVALID_API_KEY",
    "http": 401,
    "category": "AUTH_ERROR",
    "when": "Invalid or missing Bearer token"
  },
  {
    "code": "UNAUTHORIZED",
    "http": 401,
    "category": "AUTH_ERROR",
    "when": "Missing or invalid API key (alias of INVALID_API_KEY)"
  },
  {
    "code": "CHANNEL_NOT_AUTHORIZED",
    "http": 401,
    "category": "AUTH_ERROR",
    "when": "Channel not authorized for this app"
  },
  {
    "code": "FORBIDDEN",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Key valid but not permitted (e.g. channel not enabled)"
  },
  {
    "code": "INSUFFICIENT_SCOPE",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "API key missing required scope for this route"
  },
  {
    "code": "CHANNEL_NOT_ENABLED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Channel not enabled for this app"
  },
  {
    "code": "CHANNEL_AUTH_REQUIRED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Channel authorization not completed"
  },
  {
    "code": "CHANNEL_AUTH_EXPIRED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Channel authorization expired — re-authorize in Portal"
  },
  {
    "code": "CHANNEL_AUTH_REVOKED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Channel authorization revoked"
  },
  {
    "code": "FULFILLMENT_MODE_NOT_SUPPORTED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "`/v1/fulfillment/*` on self-fulfillment app (maps draft FULFILLMENT_NOT_ENABLED)"
  },
  {
    "code": "FULFILLMENT_ACCESS_REQUIRED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Reserved — fulfillment access not granted"
  },
  {
    "code": "FULFILLMENT_ACCESS_SUSPENDED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Reserved — fulfillment access suspended"
  },
  {
    "code": "WAREHOUSE_AUTH_REQUIRED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Warehouse fulfillment without warehouse authorization"
  },
  {
    "code": "WAREHOUSE_AUTH_EXPIRED",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Warehouse authorization expired"
  },
  {
    "code": "WAREHOUSE_AUTH_INVALID",
    "http": 403,
    "category": "AUTH_ERROR",
    "when": "Warehouse rejected developer authentication"
  },
  {
    "code": "VALIDATION_ERROR",
    "http": 400,
    "category": "VALIDATION_ERROR",
    "when": "Missing/invalid body fields, unsupported currency"
  },
  {
    "code": "UNSUPPORTED_CHANNEL",
    "http": 400,
    "category": "VALIDATION_ERROR",
    "when": "Unknown channel value"
  },
  {
    "code": "UNSUPPORTED_FIELD",
    "http": 400,
    "category": "VALIDATION_ERROR",
    "when": "Field not allowed on this route (e.g. currency on product)"
  },
  {
    "code": "NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Route or resource does not exist"
  },
  {
    "code": "CHANNEL_CAPABILITY_NOT_SUPPORTED",
    "http": 400,
    "category": "CHANNEL_ERROR",
    "when": "Operation not available on this channel"
  },
  {
    "code": "CHANNEL_UPSTREAM_ERROR",
    "http": 502,
    "category": "CHANNEL_ERROR",
    "when": "Marketplace rejected the call (sanitized)"
  },
  {
    "code": "WAREHOUSE_UPSTREAM_ERROR",
    "http": 502,
    "category": "CHANNEL_ERROR",
    "when": "Warehouse / fulfillment upstream failed (sanitized)"
  },
  {
    "code": "INTERNAL_ERROR",
    "http": 500,
    "category": "INTERNAL_ERROR",
    "when": "Unexpected Gateway failure — retry with backoff"
  },
  {
    "code": "RATE_LIMIT_EXCEEDED",
    "http": 429,
    "category": "RATE_LIMIT_ERROR",
    "when": "Per-minute / burst rate limit"
  },
  {
    "code": "QUOTA_EXCEEDED",
    "http": 429,
    "category": "RATE_LIMIT_ERROR",
    "when": "Daily channel quota exhausted"
  },
  {
    "code": "PLATFORM_QUOTA_EXCEEDED",
    "http": 429,
    "category": "RATE_LIMIT_ERROR",
    "when": "Platform-wide channel capacity limit"
  },
  {
    "code": "PAYMENT_DECLINED",
    "http": 402,
    "category": "VALIDATION_ERROR",
    "when": "Payment declined (sandbox: sb_ord_pay_declined)"
  },
  {
    "code": "PAYMENT_INSUFFICIENT_FUNDS",
    "http": 402,
    "category": "VALIDATION_ERROR",
    "when": "Insufficient funds (sandbox: sb_ord_pay_insufficient)"
  },
  {
    "code": "ORDER_ALREADY_PAID",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Order already paid"
  },
  {
    "code": "SHIPMENT_ALREADY_PAID",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "International shipment already paid"
  },
  {
    "code": "ORDER_CANCELLED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Order already cancelled"
  },
  {
    "code": "PRODUCT_UNAVAILABLE",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Product unavailable / delisted"
  },
  {
    "code": "IDEMPOTENCY_CONFLICT",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Duplicate external_shipment_id or idempotency key"
  },
  {
    "code": "EXTERNAL_ORDER_ID_ALREADY_EXISTS",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "external_order_id already used in this app"
  },
  {
    "code": "SHIPMENT_CREATE_EXCEPTION",
    "http": 400,
    "category": "VALIDATION_ERROR",
    "when": "Create refused (missing item attributes, parcel not inbound, etc.)"
  },
  {
    "code": "PARCEL_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Invalid or not yet inbound parcel"
  },
  {
    "code": "PACKAGE_ALREADY_CONSOLIDATED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Parcel already included in another shipment"
  },
  {
    "code": "INVALID_SHIPPING_CHANNEL",
    "http": 400,
    "category": "VALIDATION_ERROR",
    "when": "Bad shipping_channel_code"
  },
  {
    "code": "INSUFFICIENT_BALANCE",
    "http": 402,
    "category": "VALIDATION_ERROR",
    "when": "Fulfillment wallet too low (pay / return confirm / etc.)"
  },
  {
    "code": "SHIPMENT_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Shipment missing or not owned (intercept)"
  },
  {
    "code": "SHIPMENT_NOT_INTERCEPTABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Current shipment state cannot request intercept"
  },
  {
    "code": "SHIPMENT_INTERCEPTION_ALREADY_REQUESTED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Intercept already requested"
  },
  {
    "code": "INVALID_INTERCEPTION_REASON",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Intercept reason CODE is invalid"
  },
  {
    "code": "INTERCEPTION_REMARK_REQUIRED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "remark required when reason is OTHER"
  },
  {
    "code": "SHIPMENT_NOT_CANCELLABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Shipment cannot be cancelled in current status"
  },
  {
    "code": "SHIPMENT_ALREADY_CANCELLED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Shipment already cancelled"
  },
  {
    "code": "INBOUND_TRACKING_ALREADY_SHIPPED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Tracking already linked to a shipped package"
  },
  {
    "code": "INBOUND_TRACKING_ALREADY_EXISTS",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Tracking already registered"
  },
  {
    "code": "INBOUND_VALIDATION_FAILED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Inbound field errors in details.fields"
  },
  {
    "code": "INBOUND_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Inbound missing or not owned"
  },
  {
    "code": "PACKAGE_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Package missing or not owned"
  },
  {
    "code": "INBOUND_NOT_EDITABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Inbound not editable in current state"
  },
  {
    "code": "INBOUND_ALREADY_RECEIVED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Already received at warehouse"
  },
  {
    "code": "INBOUND_PACKAGE_MISMATCH",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Cannot link resource to given inbound/package"
  },
  {
    "code": "INVALID_TRACKING_NUMBER",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Tracking number format invalid"
  },
  {
    "code": "PACKAGE_COUNT_INVALID",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid package_count"
  },
  {
    "code": "TOTAL_VALUE_INVALID",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid total_value"
  },
  {
    "code": "UNSUPPORTED_CURRENCY",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Unsupported currency (inbound: CNY/USD/KRW)"
  },
  {
    "code": "UNCLAIMED_PACKAGE_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Unclaimed package missing"
  },
  {
    "code": "TRACKING_NUMBER_MISMATCH",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Claim full tracking exact-match failed"
  },
  {
    "code": "PACKAGE_ALREADY_CLAIMED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Package already claimed"
  },
  {
    "code": "PACKAGE_NOT_CLAIMABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Not claimable in current state"
  },
  {
    "code": "CLAIM_ATTEMPTS_EXCEEDED",
    "http": 429,
    "category": "RATE_LIMIT_ERROR",
    "when": "Too many failed claims on one ucp_*"
  },
  {
    "code": "RETURN_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Return missing or not owned"
  },
  {
    "code": "RETURN_NOT_CONFIRMABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Return cannot be confirmed in current status"
  },
  {
    "code": "RETURN_NOT_CANCELLABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Return cannot be cancelled in current status"
  },
  {
    "code": "RETURN_ALREADY_RETURNED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Already returned"
  },
  {
    "code": "RETURN_ALREADY_CANCELLED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Already cancelled / voided"
  },
  {
    "code": "RETURN_FEE_NOT_READY",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Return fee not calculated yet"
  },
  {
    "code": "RETURN_FEE_CHANGED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Confirm amount ≠ current fee.total"
  },
  {
    "code": "PACKAGE_NOT_RETURNABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Package status blocks return"
  },
  {
    "code": "INVALID_RETURN_REASON",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Unknown return reason code"
  },
  {
    "code": "INVALID_RETURN_ADDRESS",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid seller_return address"
  },
  {
    "code": "RETURN_VALIDATION_FAILED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Return field validation failed"
  },
  {
    "code": "VALUE_ADDED_SERVICE_NOT_FOUND",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Unknown VAS service_code"
  },
  {
    "code": "VALUE_ADDED_SERVICE_UNAVAILABLE",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "VAS exists but currently unavailable"
  },
  {
    "code": "VALUE_ADDED_SERVICE_INVALID_STAGE",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "VAS not allowed at this stage"
  },
  {
    "code": "VALUE_ADDED_SERVICE_QUANTITY_INVALID",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid VAS quantity"
  },
  {
    "code": "SERVICE_REQUEST_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Service request missing"
  },
  {
    "code": "RESOURCE_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Related resource missing"
  },
  {
    "code": "RESOURCE_NOT_ELIGIBLE_FOR_SERVICE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Package/shipment not eligible for service"
  },
  {
    "code": "SERVICE_FEE_NOT_READY",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Service fee not ready"
  },
  {
    "code": "SERVICE_FEE_CHANGED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Confirm amount ≠ current service fee"
  },
  {
    "code": "SERVICE_REQUEST_VALIDATION_FAILED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Service request field validation failed"
  },
  {
    "code": "TRANSACTION_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Transaction missing or not owned"
  },
  {
    "code": "INVOICE_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Invoice missing or not owned"
  },
  {
    "code": "TRANSACTION_NOT_INVOICEABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Transaction cannot be invoiced"
  },
  {
    "code": "TRANSACTION_ALREADY_INVOICED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Transaction already invoiced"
  },
  {
    "code": "TRANSACTION_INVOICE_PENDING",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Invoice already pending for transaction"
  },
  {
    "code": "INVOICE_NOT_DOWNLOADABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Invoice not issued yet"
  },
  {
    "code": "INVOICE_VALIDATION_FAILED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invoice request validation failed"
  },
  {
    "code": "INVOICE_CURRENCY_MISMATCH",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invoice currency mismatch"
  },
  {
    "code": "INVALID_INVOICE_TITLE",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid invoice title"
  },
  {
    "code": "INVALID_TAX_NUMBER",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid tax number"
  },
  {
    "code": "INVALID_BILLING_ADDRESS",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "billing_address missing or invalid"
  },
  {
    "code": "TICKET_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Ticket missing or not owned by Application"
  },
  {
    "code": "TICKET_NOT_REPLYABLE",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Ticket not replyable (e.g. closed)"
  },
  {
    "code": "TICKET_ALREADY_CLOSED",
    "http": 409,
    "category": "VALIDATION_ERROR",
    "when": "Ticket already closed"
  },
  {
    "code": "INVALID_TICKET_CATEGORY",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid ticket category"
  },
  {
    "code": "INVALID_TICKET_PRIORITY",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid ticket priority"
  },
  {
    "code": "INVALID_RELATED_RESOURCE",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Invalid related_resource type"
  },
  {
    "code": "TICKET_VALIDATION_FAILED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Ticket field validation failed"
  },
  {
    "code": "RELATED_RESOURCE_NOT_FOUND",
    "http": 404,
    "category": "VALIDATION_ERROR",
    "when": "Related business resource missing or not owned"
  },
  {
    "code": "MESSAGE_REQUIRED",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Message body required"
  },
  {
    "code": "MESSAGE_TOO_LONG",
    "http": 422,
    "category": "VALIDATION_ERROR",
    "when": "Message exceeds 10000 characters"
  }
]