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
{
"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 · PHP | HTTP · code | What happened, and what to do |
|---|---|---|
AuthenticationErrorAuthenticationException | 401 unauthorized | Missing, wrong or revoked key. Check which environment you are in; do not retry. |
PermissionErrorPermissionException | 403 forbidden | The key may not do this. Approving a refund, for example, is never a key's to do. |
PermissionErrorPermissionException | 403 forbidden | The 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. |
PermissionErrorPermissionException | 403 email_unverified | The account has not confirmed its email, so live actions are held. The business fixes this in the dashboard. |
NotFoundErrorNotFoundException | 404 not_found | No such reference in this mode. A live reference with a test key looks exactly like this. |
IdempotencyConflictErrorIdempotencyConflictException | 409 idempotency_conflict | The same key was used with a different body. Use a new key for a genuinely new request. |
ValidationErrorValidationException | 422 validation_failed | A field is wrong. fields (getFieldErrors() in PHP) says which, in plain language. |
ValidationErrorValidationException | 422 no_provider | The business has no provider connected in this mode. They connect one in Providers. |
RateLimitErrorRateLimitException | 429 rate_limited | Too many requests. retryAfter (getRetryAfterSeconds() in PHP) says how long to wait. |
HarbourErrorHarbourException | 502 provider_unavailable | The provider (Paystack, Flutterwave or OPay) is down or refusing. Harbour keeps polling; try again shortly. |
HarbourErrorHarbourException | 500 server_error | Our fault, and logged. Safe to retry with the same idempotency key. |
ApiConnectionErrorApiConnectionException | — no response | DNS, TLS, timeout. The request may still have happened: retry with the same idempotency key. |
SignatureVerificationErrorSignatureVerificationException | — webhook | A 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;
}
<?php
use Nordaxiz\HarbourConnect\Exception\ApiConnectionException;
use Nordaxiz\HarbourConnect\Exception\HarbourException;
use Nordaxiz\HarbourConnect\Exception\RateLimitException;
use Nordaxiz\HarbourConnect\Exception\ValidationException;
try {
$checkout = Harbour::charge($order->total_kobo, $order->email, ['reference' => $order->reference]);
} catch (ValidationException $e) {
// something about the request is wrong and will stay wrong: show it, do not retry
return back()->withErrors($e->getFieldErrors());
} catch (RateLimitException $e) {
return $this->retryAfter($e->getRetryAfterSeconds() ?? 60);
} catch (ApiConnectionException $e) {
// no answer at all. The charge may or may not exist: retry with the SAME idempotency key
report($e);
return back()->with('error', 'We could not reach payments. Try again in a moment.');
} catch (HarbourException $e) {
report($e->getErrorCode() . ': ' . $e->getMessage());
return back()->with('error', 'Payments are having a moment. Try again shortly.');
}
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
}
}
curl -s -X POST https://api.harbour.africa/v1/charges \
<?php
try {
Harbour::charge($amountKobo, $email);
} catch (ValidationException $e) {
$e->getFieldErrors(); // ['amount_kobo' => 'Amount must be at least ₦100.']
$e->getMessage(); // the same sentence, for one-line forms
}