Errors & troubleshooting

Use this reference when an API call returns a non-success status. Always check the HTTP status code first - there is no stable machine-readable error code across endpoints, and the response body shape varies.

Error Response Format

Most errors (auth failures, not-found, forbidden, validation) come back in the standard shape:

{
  "statusCode": 400,
  "message": "Amount must be greater than 0",
  "error": "Bad Request"
}

A validation failure across multiple fields instead nests an array:

{
  "statusCode": 400,
  "message": ["amount must be a positive number", "currency must be a valid ISO code"],
  "error": "Bad Request"
}

A small number of endpoints that process a payment inline (card/crypto charges) catch failures and return 200/201 with a body-level flag instead of a non-2xx status:

{ "success": false, "error": "Card payment processing failed" }

HTTP Status Codes

Reading an Error by Status Code

There is no stable machine-readable error code on these endpoints - branch on the HTTP status and read message for the human-readable reason.

Webhook delivery failures

These aren't returned to your API caller - they show up as failed deliveries to your targetUrl, retried up to 5 times with backoff. If your endpoint never receives a delivery, verify the URL is publicly reachable; if you reject deliveries with 401, recompute the HMAC-SHA256 signature over the raw body using your hookSecret (no timestamp is included) - see Webhook payload.

Code Examples

Examples below share one fund a campaign flow.

const API_KEY = process.env.UGSK_LIVE || "UGSK_live_xxx";

async function fundCampaign(campaignId, body) {
  const res = await fetch(
    `https://api.ugc.africa/automation/actions/campaigns/${campaignId}/fund`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    }
  );
  const result = await res.json();
  if (!res.ok || result.success === false) {
    throw new Error(result.message ?? result.error ?? "request failed");
  }
  return result;
}

Debugging Tips