Kanal APIGetting started
Errors
Error format, status codes, and how to handle them.
Errors are returned as JSON with the relevant HTTP status code.
Validation errors (422)
Invalid payloads return Laravel's standard validation shape:
{
"message": "The customer.phone field is required.",
"errors": {
"customer.phone": ["The customer.phone field is required."]
}
}errors is keyed by field path (dot notation for nested fields). These are
not retryable — fix the payload before sending again.
Other errors
{ "error": "API key does not authorize this store" }Status code reference
| Status | Meaning | Retry? |
|---|---|---|
200 | Updated an existing record | — |
201 | Created a new record | — |
204 | Deleted (no body) | — |
400 | Malformed request | No |
401 | Missing or invalid API key | No |
403 | Key not authorized for this store | No |
404 | Store or record not found | No |
422 | Validation failed | No |
429 | Rate limit exceeded | Yes — honor Retry-After |
5xx | Transient server error | Yes — exponential backoff |
Recommended handling
2xx → success, done
4xx (≠429) → log and alert, do NOT retry (payload/credentials bug)
429 → wait Retry-After, then retry
5xx / net → exponential backoff + jitter, retry safelyRetries are always safe because writes are idempotent on
(store_id, external_id) — see Idempotency.