Prodaksha Developers

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 answers 409, 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: 429 with Retry-After.
  • Bodies are JSON, UTF-8. Text fields have lengths (for example reference_no up to 40 characters); the API reference lists them.
  • Only HTTPS. Webhook addresses must be https:// too.