Skip to content

Errors

Use statusCode first, then error. message is written for a person, so show it or log it, but never parse it.

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.

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.