Developer docs
Errors
ZOZOPAY uses standard HTTP status codes. Errors return a JSON body with a readable message.
Error format
{
"error": "amount: Number must be less than or equal to 1000000"
}Validation errors (400) list each field and its problem in the error string, and also include a details object with the same information grouped by field.
Status codes
| Code | Meaning | What to do |
|---|---|---|
| 200 | Request succeeded. | Read the response body. |
| 201 | Resource created. | Store the returned id. |
| 400 | Invalid request body. | Fix the fields named in the message and retry. |
| 401 | Missing, malformed, wrong or revoked API key. | Check the Authorization header, or create a new key. |
| 403 | Your merchant account is not active. | Complete KYC or contact support. |
| 404 | The payment link does not exist or belongs to another merchant. | Check the ID. |
| 500 | Something went wrong on our side. | Retry after a short delay, then contact support if it persists. |
Handling errors
const res = await fetch(url, options);
if (!res.ok) {
const { error } = await res.json();
// 4xx: fix the request. 5xx: retry later.
throw new Error(`ZOZOPAY ${res.status}: ${error}`);
}
const link = await res.json();Retries: there are no idempotency keys yet. Retrying a failed POST after a network error could create a second payment link, so check your own records or use a unique receiptId first.