Errors

API errors use one consistent JSON object with a human-readable message and a machine-readable code.

Error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Customer validation failed.",
    "param": "name",
    "errors": {
      "name": {
        "_required": "This field is required"
      }
    }
  }
}

Field	Always present	Description
`type`	Yes	Broad error category.
`code`	Yes	Stable code suitable for program logic.
`message`	Yes	Human-readable explanation.
`param`	No	Request field or header associated with the error.
`errors`	No	Field-level validation details.

Use code for programmatic decisions. Messages may become clearer over time and should primarily be shown to developers.

Error types

Type	Meaning
`authentication_error`	Authentication is missing or invalid.
`permission_error`	Account access, plan limits, user permissions, or key scopes deny the action.
`invalid_request_error`	Request input, state, or a requested resource is invalid.
`rate_limit_error`	The client has exceeded an enforced request limit.
`api_error`	SalesBinder encountered an unexpected server error.

Common error codes

Code	Typical status	Meaning
`bad_request`	`400`	The request is malformed.
`authentication_required`	`401`	A valid credential is required.
`permission_denied`	`403`	The action is not permitted.
`account_access_restricted`	`403`	The SalesBinder account is not currently permitted to use the API.
`record_limit_exceeded`	`403`	The account has reached its effective subscription record limit.
`resource_missing`	`404`	The requested resource is unavailable.
`method_not_allowed`	`405`	The endpoint does not accept this HTTP method.
`conflict`	`409`	The request conflicts with the resource's current state.
`validation_failed`	`422`	One or more fields failed validation.
`unknown_parameter`	`422`	The request contains a parameter that the endpoint does not accept.
`invalid_query_parameter`	`422`	A query-string value is invalid.
`invalid_date_filter`	`400`	A date filter is not in the required format or range.
`invalid_assembly_method`	`400`	A kit list assembly-method filter is not `manual` or `automatic`.
`rate_limit_exceeded`	`429`	The API key has exhausted its current request allowance.
`invalid_idempotency_key`	`400`	The idempotency key format is invalid.
`invalid_request_body`	`400`	The request body cannot be normalized.
`idempotency_key_reused`	`409`	The key was used with different request data.
`idempotency_in_progress`	`409`	An identical request is still being processed.
`request_failed`	Varies	The request failed with another client-error status.
`api_error`	`500`	An unexpected server error occurred.

Inventory error codes

Code	Status	Meaning
`invalid_quantity_delta`	`422`	The quantity adjustment is missing, zero, or otherwise invalid.
`invalid_adjustment_reason`	`422`	The adjustment reason is invalid.
`location_mismatch`	`422`	The requested location does not match the item's inventory location.
`unsupported_inventory_feature`	`422`	The requested operation is unavailable for that inventory type or configuration.
`inventory_location_unavailable`	`422`	A usable inventory location could not be selected for the variation.
`duplicate_variation`	`409`	The selected variation attributes already exist on the item.
`variation_in_use`	`409`	The variation is referenced by existing records and cannot be deleted.
`variation_has_inventory`	`409`	The variation still has inventory and cannot be deleted.
`variation_delete_failed`	`422`	The variation could not be deleted.
`variation_location_exists`	`409`	The variation is already assigned to the requested location.
`variation_location_in_use`	`409`	The variation-location record is referenced by existing records.
`variation_location_has_inventory`	`409`	The variation location still has inventory and cannot be deleted.
`variation_last_location`	`409`	The variation's final location cannot be deleted.
`variation_location_delete_failed`	`422`	The variation location could not be deleted.

Kit error codes

Code	Status	Meaning
`invalid_kit_build`	`422`	The assembly quantity, component definition, or available component stock is invalid.
`unsupported_kit_build_field`	`422`	The request contains a field outside the manual assembly contract.
`unsupported_kit_disassembly_field`	`422`	A disassembly request contains a body field.
`kit_disassembly_failed`	`422`	The stored assembly could not be reversed and removed.

Stock-transfer error codes

Code	Status	Meaning
`invalid_stock_transfer`	`422`	A stock-transfer create or update field or line value is invalid.
`unsupported_stock_transfer_field`	`422`	The request contains a field outside the stock-transfer create or update contract.
`stock_transfer_update_not_allowed`	`409`	A completed stock transfer cannot be edited.
`invalid_stock_transfer_send`	`422`	A send date or shipping field is invalid.
`unsupported_stock_transfer_send_field`	`422`	The request contains a field outside the stock-transfer send contract.
`stock_transfer_send_not_allowed`	`409`	The transfer is not pending or its inventory can no longer be sent.
`invalid_stock_transfer_receive`	`422`	A received date or shipping field is invalid.
`unsupported_stock_transfer_receive_field`	`422`	The request contains a field outside the stock-transfer receive contract.
`stock_transfer_receive_not_allowed`	`409`	The transfer is not in transit or its inventory can no longer be received.
`stock_transfer_delete_not_allowed`	`409`	Existing transfer inventory cannot be safely reversed for deletion.
`stock_transfer_delete_failed`	`422`	The stock transfer could not be deleted.

Invoice error codes

Code	Status	Meaning
`invalid_invoice`	`422`	An invoice field or line value is invalid.
`unsupported_invoice_field`	`422`	The request contains a field outside the invoice create or update contract.
`invoice_update_not_allowed`	`422`	The invoice's current state does not allow updates.
`invoice_delete_not_allowed`	`409`	The invoice has related activity that prevents deletion.
`invoice_delete_failed`	`422`	The invoice could not be deleted.
`invalid_invoice_payment`	`422`	A manual payment field or amount is invalid for the invoice's current balance.
`unsupported_invoice_payment_field`	`422`	The payment request contains a field outside the manual-payment contract.
`invalid_invoice_refund`	`422`	A manual refund field or amount is invalid for the payment's refundable balance.
`unsupported_invoice_refund_field`	`422`	The refund request contains a field outside the manual-refund contract.
`provider_refund_required`	`409`	The payment is provider-backed and must be refunded through its integration.
`invalid_invoice_dispatch`	`422`	The dispatch request or dispatch date is invalid.
`unsupported_invoice_dispatch_field`	`422`	The request contains a field outside the invoice-dispatch contract.
`invoice_dispatch_not_allowed`	`409`	The invoice's current state does not allow dispatch.
`unsupported_invoice_cancel_field`	`422`	The request contains a field outside the invoice-cancellation contract.
`invoice_cancel_not_allowed`	`409`	The invoice's current state does not allow cancellation.

Estimate error codes

Code	Status	Meaning
`invalid_estimate`	`422`	An estimate field or line value is invalid.
`unsupported_estimate_field`	`422`	The request contains a field outside the estimate create or update contract.
`estimate_update_not_allowed`	`422`	The estimate's current state does not allow updates.
`estimate_delete_not_allowed`	`409`	The estimate has related activity that prevents deletion.
`estimate_delete_failed`	`422`	The estimate could not be deleted.
`unsupported_estimate_decline_field`	`422`	The request contains a field outside the estimate-decline contract.
`estimate_decline_not_allowed`	`409`	The estimate's current state does not allow decline.
`invalid_estimate_conversion`	`422`	The estimate-to-invoice conversion request is invalid.
`unsupported_estimate_conversion_field`	`422`	The request contains a field outside the estimate-to-invoice contract.
`estimate_conversion_not_allowed`	`409`	The estimate cannot be converted to an invoice in its current state.
`estimate_conversion_failed`	`422`	The estimate-to-invoice conversion could not be completed.
`unsupported_estimate_sales_order_conversion_field`	`422`	The request contains a field outside the estimate-to-sales-order contract.
`estimate_sales_order_conversion_not_allowed`	`409`	The estimate cannot be converted to a sales order in its current state.
`estimate_sales_order_conversion_failed`	`422`	The estimate-to-sales-order conversion could not be completed.

Purchase-order error codes

Code	Status	Meaning
`invalid_purchase_order`	`422`	A purchase-order field or line value is invalid.
`unsupported_purchase_order_field`	`422`	The request contains a field outside the purchase-order create or update contract.
`purchase_order_update_not_allowed`	`422`	The purchase order's current state does not allow updates.
`purchase_order_delete_not_allowed`	`409`	The purchase order has related activity that prevents deletion.
`purchase_order_delete_failed`	`422`	The purchase order could not be deleted.
`invalid_purchase_order_payment`	`422`	A manual payment field or amount is invalid.
`unsupported_purchase_order_payment_field`	`422`	The request contains a field outside the payment-creation contract.
`purchase_order_payment_not_allowed`	`409`	The purchase order's state or balance does not allow the payment operation.
`unsupported_purchase_order_payment_delete_field`	`422`	A payment-deletion request contains a body field.
`purchase_order_payment_delete_not_allowed`	`409`	The selected payment cannot be deleted.
`purchase_order_payment_delete_failed`	`422`	The payment could not be deleted.
`invalid_purchase_order_receive`	`422`	The receiving request or one of its line quantities is invalid.
`unsupported_purchase_order_receive_field`	`422`	The request contains an unsupported receiving field.
`unsupported_purchase_order_receive_line_field`	`422`	A receiving line contains an unsupported field.
`purchase_order_receive_not_allowed`	`409`	The purchase order cannot be received in its current state.
`invalid_purchase_order_send`	`422`	The send request or send date is invalid.
`unsupported_purchase_order_send_field`	`422`	The request contains a field outside the purchase-order-send contract.
`purchase_order_send_not_allowed`	`422`	The purchase order cannot be marked sent in its current state.

Sales-order error codes

Code	Status	Meaning
`invalid_sales_order`	`422`	A sales-order field or line value is invalid.
`unsupported_sales_order_field`	`422`	The request contains a field outside the sales-order create or update contract.
`sales_order_update_not_allowed`	`422`	The sales order's current state does not allow updates.
`sales_order_financial_update_not_allowed`	`422`	Financial or line fields cannot be changed after related processing begins.
`sales_order_delete_not_allowed`	`409`	The sales order has related activity that prevents deletion.
`sales_order_delete_failed`	`422`	The sales order could not be deleted.
`invalid_sales_order_invoice`	`422`	The invoice-creation request or a line quantity is invalid.
`unsupported_sales_order_invoice_field`	`422`	The request contains a field outside the sales-order-invoice contract.
`sales_order_invoice_not_allowed`	`409`	The sales order cannot be invoiced in its current state.
`sales_order_already_invoiced`	`409`	All sales-order quantities have already been invoiced.
`sales_order_line_already_invoiced`	`409`	The selected sales-order line has already been fully invoiced.
`sales_order_invoice_failed`	`500`	Invoice creation failed unexpectedly.
`invalid_sales_order_pack`	`422`	The packing request or a line quantity is invalid.
`unsupported_sales_order_pack_field`	`422`	The request contains a field outside the packing contract.
`sales_order_pack_not_allowed`	`409`	The sales order cannot be packed in its current state.
`sales_order_line_already_packed`	`409`	The selected sales-order line has already been fully packed.
`sales_order_pack_failed`	`500`	Fulfillment creation failed unexpectedly.
`invalid_sales_order_shipment`	`422`	The manual-shipment request is invalid.
`unsupported_sales_order_ship_field`	`422`	The request contains a field outside the manual-shipment contract.
`sales_order_ship_not_allowed`	`409`	The fulfillment cannot be shipped in its current state.
`sales_order_ship_failed`	`500`	Manual shipment failed unexpectedly.

Handling errors

Branch on the HTTP status and error.code.
Correct invalid fields using param and errors when present.
Retry only errors that are safe to retry.
Preserve the response's Request-Id when logging or reporting a problem.
Never include the API key in application logs or support messages.

Unexpected server errors intentionally return a generic message and do not expose stack traces or internal implementation details.