Tokens, errors and limits
Tokens and abilities
Send the token on every call:
Authorization: Bearer 12|aBcD…
Accept: application/json
A token belongs to one factory and carries abilities. Ask only for what you need.
| Ability | Allows |
|---|---|
read |
Company profile, consignments, intakes, run outputs, lot traces, purchase invoices and payments |
read:catalog |
Company profile, items and price lists |
write:consignments |
Declare consignments, read them, decide on a weight variance, read intakes, outputs and traces |
read:statements |
Toll statements, purchase invoices and payments |
approve:statements |
Approve or dispute toll statements and weight variances, and read them |
write:readings |
Send temperature readings from probes |
admin |
Everything above, plus registering and removing webhooks |
A token without the ability for an endpoint gets 403 FORBIDDEN with "This token lacks the ability: …". To stop an integration, the factory asks the platform to revoke its token; from then on every call answers 401.
Answers
Every answer is JSON in the same envelope:
{"success": true, "data": {}, "meta": {"next_cursor": "eyJ…", "limit": 50}, "message": "Success"}
{"success": false, "code": "VALIDATION", "message": "Validation failed", "errors": {"item.code": "Item MANGO-X is not in this factory's item list, and no mapping to one of its items exists."}}
Errors
code |
HTTP | Meaning | What to do |
|---|---|---|---|
VALIDATION |
422 | A field is missing or wrong; errors names each one |
Fix the body; do not retry as is |
UNAUTHORIZED |
401 | No token, or it was revoked | Get a new token |
FORBIDDEN |
403 | The token lacks the ability; the factory's API module or subscription is off; or a society has not given this factory access | Read message |
NOT_FOUND |
404 | No such record in this factory | Check the id or reference_no |
CONFLICT |
409 | Duplicate reference_no; an Idempotency-Key reused with another body; or the record is not in a state for this (for example a statement already approved) |
Do not retry; read the record |
RATE_LIMITED |
429 | Too many calls | Wait the Retry-After seconds |
DISABLED |
503 | The platform switched the API off for maintenance | Retry later |
SERVER_ERROR |
500 | Our fault | Retry later with the same Idempotency-Key |
Retrying safely
Networks fail. Send an Idempotency-Key header (up to 100 characters, for example a UUID) with every write, and keep it with the request until you have an answer.
- A retry with the same key and the same body returns the first answer and changes nothing.
- The same key with a different body is refused (
409). - Consignments are also unique by
reference_no: declaring the same delivery twice answers409, never a second delivery.
Paging
Lists return up to limit rows (default 50, at most 200) and meta.next_cursor. Pass it back as cursor until it is null:
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/items?limit=200&cursor=eyJ…"
To stay in step, keep the time of your last sync and pass updated_since (where the endpoint offers it), so you fetch only what changed.
Limits
- 120 calls a minute per token. Above that:
429withRetry-After. - Bodies are JSON, UTF-8. Text fields have lengths (for example
reference_noup to 40 characters); the API reference lists them. - Only HTTPS. Webhook addresses must be
https://too.
