Error Handling
How Validation Works
Ympact validates every record asynchronously after receipt. Valid records are processed and made visible in the Ympact portal. Invalid records are rejected and error details are returned through the same channel used for submission.
Message queue (JSON) — validation errors are delivered to a dedicated error queue provisioned by Ympact alongside the submission queue. Your integration should consume this queue to detect and handle rejected records programmatically.
SFTP (CSV) — validation errors are written to an error file deposited on the same SFTP server, in a dedicated output folder. Each error file corresponds to the submitted file and contains one error row per rejected record, including the error code and a description.
Common Validation Errors
| Error | Cause | Fix |
|---|---|---|
MISSING_REQUIRED_FIELD | A required field is absent or empty | Add the missing field to your payload or CSV row |
INVALID_DATE_FORMAT | Date does not match YYYY-MM-DD | Use the correct date format (e.g. 2025-01-15) |
INVALID_ENUM_VALUE | Field value is not in the allowed list | Check the allowed values table in the entity guide |
DUPLICATE_PRIMARY_KEY | A record with the same primary key already exists with different non-updatable fields | Verify the primary key values or check if the record was already sent |
SHIPMENT_NOT_FOUND | A Document references a shipment_reference_id that does not exist | Send the Shipment first, then the Document |
INVALID_NUMERIC_FORMAT | A number field contains non-numeric data | Ensure numeric fields contain valid numbers |
UNPROCESSABLE_ENTITY | Business rule violation (e.g. quantity exceeds PO line limit) | Review the request logic against the business rules |
How to Fix and Resend
To correct a rejected record:
- Identify the error from the validation feedback
- Fix the field value in your payload or CSV
- Resend the record with the same primary key
Ympact performs an upsert: if the primary key already exists, the record is updated with the new values. Only updatable fields are changed. See each entity guide for which fields can be updated.
Using traceId
Always include the traceId when reporting issues — it allows the support team to locate the request in server logs.