Errors - KetaPay Docs

Every error has the same shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "buyer.phone must be a Nigerian number in +234 format.",
    "param": "buyer.phone",
    "request_id": "req_01J9ZK7M2Q4V8XW3B6N5T0R1YH"
  }
}

Branch on code, never on message. param names the field at fault in dot notation.

Types

Type	HTTP	Meaning
`invalid_request_error`	400, 404, 409, 422	The request can’t be done as sent
`authentication_error`	401	Missing, invalid or expired key or customer token
`permission_error`	403	The key lacks a scope, or the customer isn’t the right party
`idempotency_error`	409	The `Idempotency-Key` was reused with a different body
`rate_limit_error`	429	Too many requests
`api_error`	5xx	Something failed on KetaPay’s side; retry with the same `Idempotency-Key`

Common codes

Code	What to do
`parameter_missing`, `parameter_invalid`	Fix the field named in `param`
`milestones_total_mismatch`	Make the milestones add up to `amount`
`commission_exceeds_contract`	Lower `commission.rate_bps` to your agreed maximum
`checkout_session_not_open`	The session was paid, expired or cancelled
`milestone_not_current`, `milestone_not_delivered`	Act on milestones in order
`dispute_open`	The milestone is frozen by a dispute
`customer_token_required`, `customer_token_expired`	Get a new customer token
`customer_not_allowed`	This customer isn’t the party allowed to do this
`verification_required`	The buyer must verify further for this amount
`missing_scope`	Use a key with the scope the endpoint names
`test_mode_only`	Test helpers only work with `sk_test_` keys
`idempotency_key_missing`	Add an `Idempotency-Key` to the `POST`

The full list is on the Error object in the API reference. New codes may be added.

Retries

Retry network errors, 429 and 5xx with backoff, reusing the same Idempotency-Key. The libraries do this twice by default.

import { InvalidRequestError } from '@ketapay/node'

try {
  await ketapay.escrows.milestones.release(
    escrowId,
    milestoneId,
    {},
    { customerToken },
  )
} catch (err) {
  if (
    err instanceof InvalidRequestError &&
    err.code === 'dispute_open'
  ) {
    // show "this milestone is in dispute"
  }
}

use KetaPay\Errors\InvalidRequestError;

try {
    $ketapay->escrows->milestones->release(
        $escrowId,
        $milestoneId,
        [],
        ['customerToken' => $token],
    );
} catch (InvalidRequestError $e) {
    if ($e->code === 'dispute_open') {
        // show "this milestone is in dispute"
    }
}