Errors

The Seev API uses conventional HTTP status codes and returns a consistent JSON error envelope on every failure. This page explains the error format, lists all error codes, and covers best practices for handling errors gracefully in your integration.

Error response format

All API errors return a JSON body with the same shape:

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked.",
  "param": null
}

HTTP status codes

Error codes

Authentication

Request validation

Payments

Webhooks

Infrastructure

Handling errors with the payment gateway

When using Seev.charge() to create a checkout session, errors generally fall into two categories:

1. Validation errors (before the customer sees anything) These happen when your server calls Seev.charge() with invalid parameters. Catch them and respond to your user with a meaningful message — do not redirect to the checkout URL.

2. Payment errors (after the customer completes the flow) These surface when you call Seev.callback() or Seev.transaction() to verify the result. A CHARGE_FAILED or CHARGE_EXPIRED code means the payment did not go through — show an error and let the customer try again.

Example

import Seev from '@seev/sdk';

// --- Creating a charge ---
let checkoutUrl: string;

try {
  const charge = await Seev.charge({
    type: 'checkout',
    amount: 5000,
    currency: 'GHS',
    recipient: { name: 'Jane Doe', email: 'jane@example.com' },
  });
  checkoutUrl = charge.redirect_url;
} catch (error) {
  if (error instanceof Error) {
    // Log the raw message for debugging
    console.error('[Seev] Charge failed:', error.message);

    // Return a generic message to the client — never expose raw API errors
    return res.status(500).json({ error: 'Could not initiate payment. Please try again.' });
  }
}

// --- Verifying the result after redirect ---
try {
  const result = await Seev.callback(req.body);

  if (result.status === 'success') {
    // Fulfil the order
  } else {
    // Payment declined — prompt the user to retry
    return res.status(400).json({ error: 'Payment was not completed.' });
  }
} catch (error) {
  if (error instanceof Error) {
    console.error('[Seev] Callback error:', error.message);
    return res.status(400).json({ error: 'Invalid payment callback.' });
  }
}

Best practices

Never display raw API error messages to users

The message field is intended for logs and developers. It may contain internal details that are confusing or misleading to end users. Map error codes to friendly copy in your UI instead.

Use code for programmatic handling

Always branch on code, not message. The message may change across API versions; the code is stable.

switch (errorCode) {
  case 'CHARGE_FAILED':
    return 'Your payment was declined. Please try a different payment method.';
  case 'CHARGE_EXPIRED':
    return 'Your payment session timed out. Please start again.';
  default:
    return 'Something went wrong. Please try again or contact support.';
}

Retry 5xx errors with exponential backoff

INTERNAL_ERROR (500) and RATE_LIMITED (429) are transient. Retry with increasing delays — for example, 1s, 2s, 4s — with a maximum of 3–4 attempts. Do not retry 4xx errors as they indicate a problem with the request itself.

Log the full error context

Include the error code, message, param, and the relevant resource ID (e.g. transaction reference) in your logs so you can correlate failures in your monitoring tools.

Handle webhook signature failures silently

If Seev.webhook() throws an INVALID_SIGNATURE error, return a 200 response anyway — do not return 401 or 400. Returning a non-2xx status will cause Seev to retry the delivery, which can amplify noise from malformed requests. Just discard the event and log the failure.