Error Handling & Retry
Queue-based event processing, retry logic, and collect endpoint status codes.
Tugus processes events queue-based via Laravel Horizon. Delivery failures are retried automatically.
Retry logic
| Attempt | Delay | Behavior |
|---|---|---|
| 1 | immediately | First delivery attempt |
| 2 | 60s | Exponential backoff |
| 3 | 300s | Exponential backoff |
| 4 | 900s | Final attempt |
| — | — | Status → failed, health check alert |
HTTP status codes — collect endpoint
| Status | Meaning |
|---|---|
| 202 | Event accepted and queued |
| 400 | Invalid payload (missing event field, malformed JSON) |
| 401 | Invalid or unknown API key |
| 422 | Validation error — see below |
| 429 | Rate limit exceeded (plan-dependent) |
Common 422 causes
The response body names the exact fields, e.g.:
{
"message": "The data.value field is required. (and 1 more error)",
"errors": {
"data.value": ["The data.value field is required."],
"data.currency": ["The data.currency field is required."]
}
}| Cause | Fix |
|---|---|
data.value / data.currency missing on a purchase/refund | Nest both inside data — they are required for these events. |
value/currency sent at the top level | Move them into data. Top-level commerce fields are not read. |
value is not numeric (e.g. "99,80") | Send a number with a . decimal separator: 99.80. |
currency not 3 letters | Use an ISO 4217 code, e.g. EUR. |
Checking delivery status
Delivery Health (Commerce Operations) shows the delivery rate and status per platform. Individual deliveries — including failures with the error message from the target API — are listed in the Transmission Log (filter by status). Live incoming events are visible under Live-Monitor.
A 202 from the collect endpoint only means that Tugus accepted the event — not that forwarding succeeded. Check the delivery status separately in the dashboard.