Errors

When a request fails, the API responds with a non-2xx status and a short plain-text body that describes the problem. Validation errors are the exception: their body is JSON (sent as text/plain, so parse it yourself).

Response bodies

Most errors return the message as text:

HTTP/2 401
content-type: text/plain

Invalid API key

Validation errors (a missing or wrong-typed field) return 422 with a JSON body. Show summary to developers and use property to find the field:

{
  "type": "validation",
  "on": "body",
  "property": "/amount",
  "message": "Expected required property",
  "summary": "Property 'amount' is missing",
  "expected": { "transactionId": "", "amount": 0 },
  "found": { "transactionId": "order_123" }
}

on is where the problem is: body, query or params. The body can also include an errors array with every failing field.

HTTP statuses

Common errors

Handle errors with moosyl-sdk

moosyl-sdk throws an AppException for failed requests. It isn't exported, so check error.name. Its fields:

• message: the API's message (for validation errors, the first issue's message).
• status: the HTTP status, when the API answered.
• code: connection_error, timeout (requests time out after 60 seconds) or abort_error when the request never got an answer; otherwise the plain-text body or unknown.
• Helpers: isClientError, isServerError, isConnectionError, isTimeout.

import { Moosyl } from "moosyl-sdk";

const moosyl = new Moosyl(process.env.MOOSYL_SECRET_KEY!);

try {
  const session = await moosyl.createCheckoutSession({
    transactionId: "order_123",
    amount: 2500,
    successUrl: "https://example.com/orders/123/paid",
    cancelUrl: "https://example.com/orders/123",
    expiresInMinutes: 30,
  });
  // redirect to session.checkoutUrl
} catch (error) {
  if (error instanceof Error && error.name === "AppException") {
    const { status, message, code } = error as Error & { status?: number; code: string };

    if (code === "connection_error" || code === "timeout") {
      // No answer from Moosyl: safe to retry this call (see below).
    } else if (status === 401 || status === 403 || status === 404) {
      // Wrong key, key type or environment: fix configuration, don't retry.
    } else {
      console.error("Moosyl error", status, message);
    }
  }
  throw error;
}

Webhook signature failures throw WebhookSignatureError instead. See Webhooks.

Retrying safely

Your transactionId is what makes retries safe: it's unique per environment, so Moosyl never creates two payment requests for the same order.

• Checkout sessions are safe to retry. Creating a session with a transactionId that already has a payment request reuses that request, and an open session for it is reused too.
• POST /payment-request is not idempotent. A second call with the same transactionId returns 409. If a create call timed out, first look the request up with GET /payment-request/by-transaction/{transactionId}, and only create it if that returns 404.
• Retry connection errors, timeouts, 500 and 502, with a short backoff (for example 1 s, 2 s, 4 s).
• Don't retry 400, 401, 403, 404, 409 or 422 without changing the request.
• Payments: don't resubmit a payment just because the call failed. Check the payment request's payments, or wait for the webhook, before asking the customer to pay again.

Webhook delivery failures

If your endpoint is down or returns an error, Moosyl retries the delivery. What's retried, how often, and how to skip duplicates is on the Webhooks page.