Reference

Errors

Every error Harbour can answer with, and what to do about each one.

Every error Harbour answers with carries a machine-readable code and a sentence a person can read. The sentences are written to be shown to a business owner, not decoded by one, so validation messages are safe to put on screen as they are.

The shape of an error

JSON
{
  "error": {
    "code": "validation_failed",
    "message": "Amount must be at least ₦100.",
    "fields": { "amount_kobo": "Amount must be at least ₦100." }
  }
}

In the SDKs this becomes a typed error. Everything at runtime extends HarbourError in Node.js (HarbourException in PHP), so one catch can be your backstop.

The errors

Node.js · PHPHTTP · codeWhat happened, and what to do
AuthenticationError
AuthenticationException
401 unauthorizedMissing, wrong or revoked key. Check which environment you are in; do not retry.
PermissionError
PermissionException
403 forbiddenThe key may not do this. Approving a refund, for example, is never a key's to do.
PermissionError
PermissionException
403 forbiddenThe business's plan does not include this, for example reading transactions on Starter. The message names the plan that does; the business upgrades in Settings → Billing. See Keys.
PermissionError
PermissionException
403 email_unverifiedThe account has not confirmed its email, so live actions are held. The business fixes this in the dashboard.
NotFoundError
NotFoundException
404 not_foundNo such reference in this mode. A live reference with a test key looks exactly like this.
IdempotencyConflictError
IdempotencyConflictException
409 idempotency_conflictThe same key was used with a different body. Use a new key for a genuinely new request.
ValidationError
ValidationException
422 validation_failedA field is wrong. fields (getFieldErrors() in PHP) says which, in plain language.
ValidationError
ValidationException
422 no_providerThe business has no provider connected in this mode. They connect one in Providers.
RateLimitError
RateLimitException
429 rate_limitedToo many requests. retryAfter (getRetryAfterSeconds() in PHP) says how long to wait.
HarbourError
HarbourException
502 provider_unavailableThe provider (Paystack, Flutterwave or OPay) is down or refusing. Harbour keeps polling; try again shortly.
HarbourError
HarbourException
500 server_errorOur fault, and logged. Safe to retry with the same idempotency key.
ApiConnectionError
ApiConnectionException
— no responseDNS, TLS, timeout. The request may still have happened: retry with the same idempotency key.
SignatureVerificationError
SignatureVerificationException
— webhookA delivery failed its signature or timestamp check. Answer 400 and look at which secret you used.

Mistakes Harbour catches before anything is sent — a float amount, an unknown option, a public key used as a secret key, a plain-HTTP base — throw InvalidArgumentError in Node.js and InvalidArgumentException in PHP. Those are bugs in the calling code, not runtime conditions.

Handling them well

import { ValidationError, RateLimitError, ApiConnectionError, HarbourError } from '@nordaxiz/harbour-connect';

try {
  const checkout = await harbour.charges.create({
    amountKobo: order.totalKobo,
    customer: order.email,
    reference: order.reference,
  });
} catch (e) {
  if (e instanceof ValidationError) {
    // something about the request is wrong and will stay wrong: show it, do not retry
    return res.status(422).json({ errors: e.fields });
  }
  if (e instanceof RateLimitError) {
    return retryLater(e.retryAfter ?? 60);
  }
  if (e instanceof ApiConnectionError) {
    // no answer at all. The charge may or may not exist: retry with the SAME idempotencyKey
    console.error(e);
    return res.status(503).json({ error: 'We could not reach payments. Try again in a moment.' });
  }
  if (e instanceof HarbourError) {
    console.error(`${e.code}: ${e.message}`);
    return res.status(502).json({ error: 'Payments are having a moment. Try again shortly.' });
  }
  throw e;
}

Every error carries the HTTP status and Harbour's code (e.status and e.code in Node.js, getHttpStatus() and getErrorCode() in PHP): log the code, not the message, so a reworded sentence never breaks a dashboard you built on top of your logs.

Showing validation errors

try {
  await harbour.charges.create({ amountKobo, customer: email });
} catch (e) {
  if (e instanceof ValidationError) {
    e.fields;    // { amount_kobo: 'Amount must be at least ₦100.' }
    e.message;   // the same sentence, for one-line forms
  }
}