Reference
Rate limits, uploads & media
Which endpoints are rate limited, the upload size and type rules, and how image and document URLs behave.
Rate limits#
A few endpoints are limited per minute. Going over returns 429 with a Retry-After header saying how many seconds to wait.
| Endpoint | Limit | Why |
|---|---|---|
| Login: customer, driver, merchant | 5 / min per phone from one address, and 60 / min per address | Slows password guessing |
payments/intent, payments/verify |
20 / min per customer, together | Each call writes a payment row or calls Moyasar |
| Opening a Return (customer) | 10 / min | Writes rows and stores photos |
| Counter Return (merchant) | 30 / min | Same |
| Invoice and credit note PDFs | 20 / min | Rendering a PDF is expensive |
init/agent-update |
60 / min | Public endpoint polled by the sync agent |
| Moyasar webhook | 120 / min | Public endpoint |
Today the customer limits on payments, PDFs and Returns share one counter per customer, so heavy use of one can return 429 on another; a fix is planned. Other endpoints have no per-minute limit today. Do not treat that as a promise: retry a 429 after Retry-After, never in a tight loop.
Uploads#
Uploads are multipart/form-data. A file over the limit or of the wrong type returns 422 under the field's name.
| Field | Accepted | Max size |
|---|---|---|
avatar (customer, driver), logo (merchant), offer image |
images | 2 MB |
Return photos[] |
images, up to 5 per party | 8 MB each |
Driver id_card, driving_license, delivery_license |
PDF, JPG, PNG | 10 MB |
Store commercial_registry_attached, license_attachment |
PDF, JPG, PNG | 10 MB |
Endpoints that take a file also accept POST where you would expect PUT (for example profile and offer updates), because PHP only reads multipart bodies on POST. Use POST whenever you send a file.
Image and file URLs#
- Every image field in a response is a full URL, ready to load:
avatar_url,logo_url,image,images_urls,image_url. Never build one from a path. - A missing image is
null, not an empty string. - Return photos are signed URLs that stop working after 30 minutes. Re-fetch the Return to get fresh ones rather than caching the URL.
- Identity and licence documents are only returned to their owner (the driver, or the store's merchant). They never appear in other people's payloads.