Errors

Errors use conventional HTTP statuses and always return the same object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: price.",
    "param": "price",
    "doc_url": "https://api.kibanda.africa/docs/errors#parameter_missing"
  }
}

Branch on type and code (stable); show message to people (it may change). param names the offending field when there is one.

Types

Type	Status	Retry?
`invalid_request_error`	400	No — fix the request.
`authentication_error`	401	No — check the key.
`permission_error`	403	No.
`not_found_error`	404	No.
`conflict_error`	409	No — the object's state doesn't allow it.
`idempotency_error`	400 / 409	409: yes, shortly. 400: no — use a new key.
`rate_limit_error`	429	Yes, with backoff.
`api_error`	500	Yes, with the same `Idempotency-Key`.

Codes

parameter_missing

A required field wasn't sent. param names it.

parameter_invalid_string

parameter_invalid_integer

parameter_invalid_boolean

parameter_invalid_number

parameter_invalid_array

parameter_invalid_object

A field has the wrong type or is out of range. Money is an integer in cents: send 25000, not 250.00 or "250".

parameter_invalid_metadata

metadata must be an object of up to 50 keys (≤ 40 characters) with string values (≤ 500 characters).

parameter_invalid_cursor

starting_after must be the id of an object from the previous page.

parameter_unknown

The field can't be set here. Order status, for example, changes through actions such as POST /v1/orders/{id}/cancel.

invalid_json

The body isn't a JSON object.

phone_invalid

Phones may be +254712345678, 254712345678 or 0712 345 678; other countries in E.164 (+256…).

email_invalid

url_invalid

Webhook URLs must be https://.

currency_unsupported

Only KES for now.

event_type_unknown

See the event types.

limit_reached

Too many API keys (20) or webhook endpoints (16).

resource_missing

No object with that id in this shop (or it belongs to another shop).

external_id_taken

Another object already has that external_id. To sync a catalog, use POST /v1/products/batch, which upserts by external_id.

customer_exists

A customer with that phone exists; the message includes their id. Pass "upsert": true to update them instead.

order_not_cancellable

The order is paid, completed, already cancelled, or a payment is in progress.

idempotency_key_reused

The key was used with a different request. Each distinct request needs its own key.

idempotency_key_invalid

Keys can be at most 255 characters.

idempotency_request_in_progress

The first request with this key hasn't finished. Retry in a moment.

unauthenticated

api_key_invalid

api_key_wrong_environment

session_required

See Authentication.

route_not_found

No such endpoint. Paths start with /v1/.

internal_error

Our fault, and it's been reported. Retrying with the same Idempotency-Key is safe.