Reference
Errors and limits
Error shape#
Failures are application/problem+json with a stable code you can switch on:
json
{ "title": "SKU 'RICE-5' is invalid (letters, digits and . _ - /, max 40).", "status": 400, "code": "validation" }| Status | code |
Meaning | Retry? |
|---|---|---|---|
| 400 | validation |
The request is wrong. The title says how. | No: fix it |
| 401 | unauthorized |
No or bad credential, wrong signature, or a stale timestamp | No: fix the credential |
| 403 | forbidden |
Valid credential, not allowed to do that | No |
| 404 | not_found |
Not found, or outside your tenant (the two look identical on purpose) | No |
| 409 | conflict |
Already exists, or an idempotency key was reused for different content | No |
| 422 | unprocessable |
Cannot succeed as sent (for example a sale line for an unknown item). Kept for review where relevant | No |
| 503 | unavailable |
A feature isn't set up on this server (for example picture storage) | Later |
| 5xx | Our side | Yes, with backoff |
Retrying safely#
Everything that creates something is idempotent by an id you choose (externalId, saleId, eventId, Idempotency-Key). Retry any request that timed out or returned 5xx with the same
id and body. For sales, the same saleId with different contents is 409, never a silent overwrite.
Conventions#
- Money: integer kobo. Quantities: decimals with up to three places.
- Time: ISO 8601 with an offset. We store UTC and report in Nigerian time where a "day" matters.
- Pagination:
page(from 1) andpageSize(up to 200). Lists return{ items, pageNumber, pageSize, total }. Catalog and sync feeds use acursorinstead. - Enums are strings (
"Completed","Card"). - Unknown fields in a request are ignored; do not rely on that.
Limits#
| Sync batch | 500 items |
| Transactions batch | 500 items |
| CSV import (sync kinds) | 5 MB, 50,000 rows |
| Product import | 5 MB, 2,000 rows |
| Product picture | 6 MB, 8,000 px a side |
| Network report range | 93 days |
| Webhook endpoints | 10 per organisation |
| Signature clock skew | 5 minutes |
There are no published request-rate limits yet. Be considerate: batch where batches exist, and back off on 5xx. If you plan sustained high volume, tell us so we can size for it.