Troubleshooting
Calls refused
| Answer | Usual cause | What to do |
|---|---|---|
401 UNAUTHORIZED |
Token missing, mistyped, or revoked | Send Authorization: Bearer <token>; ask the factory for a new token |
403 "This token lacks the ability: …" |
The token was issued without that ability | Ask the factory for a token with it (Tokens, errors and limits) |
403 on every call with a good token |
The factory's API and webhooks module is off, its plan has no API access, or its subscription is not active | The factory checks its modules and subscription |
403 "has not given this factory access" |
A society named in sender has not consented to this factory in its own system (FPOBox) |
The society connects to the factory; wait for the next sync |
422 on item.code |
The code is not one of the factory's items, and not mapped | Use a code from GET /items, or ask the factory to map your product |
422 on unit |
The unit code is not one of the factory's units | Use kg or a unit the item lists in GET /items |
409 "already exists" |
The reference_no was declared before |
Read it with GET /consignments/{reference_no}; never reuse a number |
409 on approve or dispute |
The statement or variance is not waiting for a decision (already decided, or still a draft) | Read the record; decide only once |
429 RATE_LIMITED |
More than 120 calls a minute | Wait Retry-After seconds; page with limit=200; use updated_since |
503 DISABLED |
Maintenance | Retry later |
A toll delivery is refused
"No toll client … is set up at this factory": you sent "mode": "toll", but the factory has not made your society a toll client linked to your id. The factory sets it up under Toll Processing, linked to the same sender.external_system and sender.society_id you send.
Events do not arrive
- Is the endpoint registered with this factory's token?
GET /webhooks. - Is the address reachable from the internet over
https://, with a valid certificate? - Does your receiver answer
2xxwithin 10 seconds? Reply first, process afterwards. - Does your signature check use the raw body? Parsing and re-encoding JSON changes the bytes, and the signature no longer matches.
- Is your clock right? A
X-Timestampyou think is "too old" can be your clock being wrong. - Did the event happen before you registered? Endpoints get only events from their creation on.
Results look wrong
| What you see | Why |
|---|---|
Two or three run.completed for one run |
The run used goods from several of your deliveries; you get one per reference_no, each with its share |
grade is null |
The output is a by-product or waste, or the factory's item is not one of a graded family |
| Outputs arrive days after the delivery | The factory processes when it is ready; a dry mill may wait for a full lot |
A different reference_no than you expected |
The lot was made from several deliveries; trace it with GET /lots/{lot_no}/trace |
| Amounts in another currency | The factory works in its own currency (GET /company); a sale abroad may be in USD with its rate |
Still stuck
Collect the request (method, path, body without the token), the answer, the time, and the X-Event-Id if it is about an event, and send them to the factory you integrate with, so it can pass them to the Prodaksha team.
