Errors and limits

Every error is JSON with a machine code and an English message; validation errors add issues:

{ "code": "VALIDATION_FAILED", "message": "Request validation failed",
  "issues": [ { "path": "deliveryDate", "message": "YYYY-MM-DD" } ] }

HTTP	code	What to do
400	VALIDATION_FAILED	fix the data using issues
400	REFERENCE_NOT_FOUND	a referenced record (point, warehouse) does not exist
400	INVALID_IDEMPOTENCY_KEY, INVALID_WEBHOOK_URL, INVALID_SCOPE	fix the request
401	UNAUTHENTICATED, INVALID_API_KEY	check the key; do not retry unchanged
403	FORBIDDEN, API_KEY_NOT_ALLOWED	missing permission — ask your administrator
404	—	not found (or belongs to another company — indistinguishable)
409	DUPLICATE (+field), PLAN_NOT_DRAFT, IDEMPOTENCY_IN_PROGRESS	data conflict
422	IDEMPOTENCY_KEY_REUSED	use a new Idempotency-Key for new content
429	RATE_LIMITED	wait Retry-After seconds
5xx	—	retry with back-off (same Idempotency-Key)

Limits

• 600 requests per minute per API key (may depend on the plan). Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset on every answer.
• Order batches: up to 1000 rows and 1 MB per request. Lists: limit + offset paging.

Retries

429 — wait Retry-After; 5xx and network errors — retry after 1, 2, 4, 8… seconds (up to 5 attempts) with the same Idempotency-Key. Other 4xx need a different request.