Errors
Use statusCode first, then error. message is written for a person, so show it or log it, but never parse it.
Error bodies
Section titled “Error bodies”An error with a code has error set to the code, and sometimes extra fields:
{ "statusCode": 409, "error": "CREDIT_LIMIT_EXCEEDED", "creditLimit": "500000.00", "exposure": "497940.00", "shipmentAmount": "3732.00", "message": "This Shipment would take what you owe Tujyane past your credit limit of 500000.00 RWF. Pay your balance or contact Tujyane."}A validation failure has errors and no error field. path names the field. The items can carry more fields, such as origin, format or pattern.
{ "statusCode": 400, "message": "Validation failed", "errors": [ { "code": "invalid_format", "path": ["recipient", "phone"], "message": "Enter a Rwandan mobile number" } ]}Other errors have error set to the HTTP reason, such as "Not Found", "Unauthorized" or "Bad Request".
A temporary failure answers 503 with "code": "TRY_AGAIN" and a Retry-After: 1 header. Retry the same request. For a write, send the same Idempotency-Key.
With Accept-Language: fr or rw, message is translated, and messageEn holds the English text.
Error codes
Section titled “Error codes”| Status | error |
Routes | Meaning and extra fields |
|---|---|---|---|
| 400 | none, errors[] |
Any with a body, query or id | Validation failed. Check Content-Type: application/json on requests with a body. |
| 400 | Bad Request |
Writes | Idempotency-Key must be 8-255 chars |
| 400 | Bad Request |
GET /shipments |
Invalid pagination cursor |
| 401 | Unauthorized |
All | Missing, unknown or revoked key |
| 403 | CLIENT_DISABLED |
All | Your account is disabled |
| 404 | Not Found |
Routes with :id |
No such Shipment for this account and key mode |
| 409 | NO_TARIFF |
Quote, create | No tariff for this size class. sizeClass |
| 409 | CREDIT_LIMIT_EXCEEDED |
Create, confirm (live keys) | creditLimit, exposure, shipmentAmount |
| 409 | CONFIRMATION_EXPIRED |
Confirm | Past confirmBy. Create a new Shipment. |
| 409 | SHIPMENT_CANCELLED |
Confirm | Cancelled before it was confirmed. Create a new Shipment. |
| 409 | SHIPMENT_STATE_CONFLICT |
Confirm, retry | The Shipment changed during your request. currentStatus. Read it again, then retry. |
| 409 | CANNOT_CANCEL_AFTER_PICKUP |
Cancel | The partner has the parcel, or the Shipment is delivered or returned. |
| 409 | ILLEGAL_SHIPMENT_TRANSITION |
Cancel | Already cancelled or expired, or the retry window closed. from, to, actor |
| 409 | RETRY_CLOSED |
Retry | Not NO_PARTNER_FOUND, or noPartnerDeadlineAt has passed |
| 409 | NOT_DELIVERED |
Not received | The Shipment is not DELIVERED |
| 409 | REPORT_WINDOW_CLOSED |
Not received | More than 24 hours since delivery |
| 409 | ALREADY_REPORTED |
Not received | You already reported it |
| 409 | NO_WEBHOOK_URL |
Test webhook | No webhook URL is set |
| 409 | REQUEST_IN_PROGRESS |
Writes | A request with the same Idempotency-Key is still running |
| 422 | OUTSIDE_SERVICE_AREA |
Quote, create | point: pickup or dropoff |
| 429 | RATE_LIMITED |
All | retryAfterSeconds, also in the Retry-After header |
| 503 | Service Unavailable |
All | code: "TRY_AGAIN". Retry after Retry-After. |
| Other 5xx | All | Retry with backoff. For writes, send the same Idempotency-Key. |

