ATTENTION, FAILED & retries

Driving orders via the API

Attention — a person is needed

ATTENTION is not an error. Extraction finished (result is there) but at least one thing needs judgement. Find out what:

Signal in result	Meaning	Typical fix
items[i].article_number == null	line could not be resolved to your catalog	add the product or a customer item mapping; operator picks the article
customer.customer_id == null	sender not identified with confidence	check the customer record (VAT, e-mail, address); operator picks the customer
items[i].quantity_state == "Unrecognised"	quantity present but unreadable (handwritten, smudged)	operator enters it
state mentions a master-data disagreement	document says X, your record says Y	operator confirms; you may update the master record
all lines dropped (assortment sheet, nothing ordered)	nothing to book	operator cancels

What you can do headless:

• Route it. Create a ticket / send an e-mail with the AIOTIC app link (https://<app>/orders?...) and the reason. The OrderWatcher gives you the transition.
• Learn from it. When an operator resolves an unknown article and the line carries a customer_item_number, create the mapping so the next order from that customer resolves automatically.
• Do not auto-send it. Sending an ATTENTION order via POST /erp/send is allowed — it is an explicit override — but it hands your ERP a payload with null article numbers or customer. Reserve it for a human who looked.

Failed — terminal error

Something structural went wrong (last_error says what: unreadable file, no text, a processing error that exhausted retries). One retry is reasonable, then alert:

POST/order/retry/{request_id}integration key

if status.status == "FAILED" and status.retry_count == 0:
    new = client.orders.retry(status.request_id)    # 400 if not FAILED
    track(new.request_id)                          # the OLD id becomes REPROCESSED

A retry creates a new order with the same files; the original becomes REPROCESSED and keeps its history. Track the new id from then on.

Queued (retry) — AIOTIC is retrying

Transient failures (temporary upstream outage, timeout) are retried automatically with backoff. next_retry_at tells you when; retry_count how often. Do nothing — do not call /order/retry, it is only for FAILED.

Rejected e-mails

Not an order status at all: a mail the classifier decided is not a purchase order. See Rejected e-mails.

Decision table for an automated service

match status.status:
    case "PROCESSED":                       book_or_send(status)
    case "ATTENTION":                       route_to_human(status)
    case "FAILED" if status.retry_count == 0: client.orders.retry(status.request_id)
    case "FAILED":                          alert(status.last_error)
    case "RETRY_PENDING" | "QUEUED" | "PROCESSING" | "SENDING": pass
    case "SENT":                            reconcile_erp_ref(status.erp_ref)
    case "MODIFIED":                        book_or_send(status)   # operator edited in the app
    case "REPROCESSED" | "CANCELED":        stop_tracking(status.request_id)
    case _:                                 log.warning("unknown status %s", status.status)  # forward compatible