Error Codes

Every error code the Swipe API returns, with its HTTP status, cause, and how to resolve it.

Failed requests return the standard response envelope with success: false and a stable error_code:

{
  "success": false,
  "message": "The provided hash ID is invalid.",
  "error_code": "INVALID_HASH_ID",
  "errors": {}
}

Handle errors by error_code, not by matching message text — messages can change, codes are stable. Validation and business errors come with HTTP 400, authentication failures with 401, and unexpected failures with 500 (safe to retry with backoff).

Document errors

All returned with HTTP 400.

Error code	Cause and resolution
HASH_ID_MISSING	No hash_id in the request. Pass the hash_id returned when the document was created.
INVALID_HASH_ID	The hash_id doesn’t match any document. Check for typos, or find it via List of documents.
DUPLICATE_DOC_SERIAL_NUMBER	A document with this serial number already exists. If this was a retry, the original succeeded — fetch it instead of re-creating. Otherwise use a new serial number.
DOCUMENT_TYPE_NOT_FOUND	Unknown document_type. Use one of the values listed in Documents.
INVALID_DOCUMENT_NUMBER / INVALID_SERIAL_NUMBER	The document/serial number is malformed. Check the serial_number (or serial_number_v2) format.
DUPLICATE_SUPPLIER_INVOICE_SERIAL_NUMBER	A purchase with this supplier invoice serial already exists.
FORBIDDEN_USING_BACK_DATE	Back-dated documents are disabled on your account’s settings. Use the current date or change the setting in the dashboard.
INVALID_TAX_RATE	The tax_rate is not a valid GST rate.
ITEM_NOT_FOUND	The referenced item doesn’t exist. Check the item id, or send full item details to auto-create it.
CUSTOMER_NOT_FOUND / INVALID_CUSTOMER_ID	The referenced customer doesn’t exist or the ID is malformed. Check the party.id, or send full party details to auto-create.
INSUFFICIENT_STOCK	The sale would take stock below zero. Add stock via Inventory or adjust the quantity.
BATCH_OR_SERIAL_NUMBER_NOT_SELECTED	The item is batch/serial tracked; the document must specify which batch or serial numbers move.
DUPLICATE_PRODUCT_SERIAL_NUMBER	This product serial number is already in stock.
RETURN_NOT_POSSIBLE_FOR_AVAILABLE_SERIAL_NUMBER	The serial number being returned is already in stock, so it can’t be returned again.
CAN_NOT_APPLY_TDS_AND_TCS_TOGETHER	A document can carry TDS or TCS, not both. Send only one of tds_id / tcs_id — see Tax codes.
TDS_DETAILS_NOT_FOUND / TCS_DETAILS_NOT_FOUND	The tds_id / tcs_id doesn’t match a known code. Use an ID from Tax codes.
MISSING_BANK_ACCOUNT / BANK_DETAILS_MISSING_NON_CASH	Non-cash payments need a bank account configured on your Swipe account. Add one in the dashboard.
AMOUNT_RECEIVED_GREATER_THAN_TOTAL_AMOUNT	The payment amount exceeds the document total. Reduce amount_received / amount_paying.
SUBSCRIPTIONS_NOT_ENABLED	Enable subscriptions in the dashboard before creating document_type=subscription.
SUBSCRIPTION_DETAILS_NOT_FOUND	document_type=subscription needs a subscription_details object — see Subscriptions.
INVALID_REPEAT	subscription_details.repeat / repeat_type is invalid. Use a positive number with one of days, weeks, months, years.
INVALID_CUSTOM_COLUMN_VALUE / INVALID_HEADER_FORMAT	A custom column value or custom header doesn’t match the columns configured on your account.
EINVOICE_NOT_FOUND	No e-invoice exists for this document. Generate one by creating the document with einvoice: true.
FREE_USER_EXPORT_LIMIT_EXCEEDED	Export document limit on the free plan reached. Upgrade the account to continue.

E-invoice and e-way bill portal errors

Error code	Cause and resolution
PORTAL_ERROR_{code}	The government portal rejected the request; {code} is the portal’s own error number (for example PORTAL_ERROR_2247). Look the code up in the official e-invoice error list — common causes are GSTIN mismatches, wrong state codes, and duplicate IRNs.

Customer, vendor, and product errors

All returned with HTTP 400.

Error code	Cause and resolution
CUSTOMER_ALREADY_EXISTS	A customer with this id already exists. Use Update a customer instead of adding again.
CUSTOMER_NOT_FOUND	No customer with this customer_id. Check the ID or list customers to find it.
INVALID_CUSTOMER_ID	The customer_id is malformed.
PRODUCT_ALREADY_EXISTS	An item with this id already exists. Use Update an item instead of adding again.

Authentication errors

Returned with HTTP 401 — see Authentication.

Error code	Cause and resolution
UNAUTHORIZED	The API key is missing, malformed, or invalid. Send Authorization: Bearer YOUR_API_KEY.
FORBIDDEN	The key is valid but not allowed to perform this action. Check the account’s plan and permissions.

General errors

Error code	HTTP status	Cause and resolution
BAD_REQUEST	400	The request is malformed — invalid JSON, wrong types, or missing required fields. Check errors for field-level details.
UNKNOWN_ERROR	500	Something failed on Swipe’s side. Retry with backoff; if it persists, contact support with the request details.