Yativo API Responses & Error Handling

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "status_code": 200,
  "message": "Request successful",
  "data": {
    "id": "...",
    "...": "..."
  }
}

{
  "status": "success",
  "status_code": 200,
  "message": "Records retrieved successfully",
  "data": [
    { "id": "...", "...": "..." }
  ],
  "pagination": {
    "total": 134,
    "per_page": 20,
    "current_page": 1,
    "last_page": 7,
    "next_page_url": "https://api.yativo.com/api/v1/...?page=2",
    "prev_page_url": null
  }
}

HTTP/1.1 422 Unprocessable Entity

{
  "status": "failed",
  "status_code": 422,
  "message": "The amount field is required.",
  "data": {
    "amount": ["The amount field is required."],
    "debit_wallet": ["The debit wallet field is required."]
  },
  "error": {
    "code": "invalid_argument",
    "message": "The amount field is required.",
    "request_id": "req_8f1c2a3b4c5d6e7f8a9b0c1d"
  },
  "error_details": {
    "code": "validation_error",
    "message": "The amount field is required.",
    "http_status": 422,
    "fields": {
      "amount": ["The amount field is required."],
      "debit_wallet": ["The debit wallet field is required."]
    },
    "retryable": false,
    "retry_after": null
  }
}

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": { "error": "Insufficient wallet balance" },
  "error_details": {
    "code": "bad_request",
    "message": "Insufficient wallet balance",
    "http_status": 400,
    "fields": { "error": ["Insufficient wallet balance"] },
    "retryable": false,
    "retry_after": null
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "message": "Too Many Attempts.",
  "error_details": {
    "code": "rate_limited",
    "message": "Too Many Attempts.",
    "http_status": 429,
    "fields": { "error": ["Too Many Attempts."] },
    "retryable": true,
    "retry_after": 1
  }
}

HTTP/1.1 400 Bad Request

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": {
    "error": "Insufficient wallet balance"
  }
}

HTTP/1.1 422 Unprocessable Entity

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "customer_email": ["The customer email field is required."],
    "customer_phone": ["The customer phone format is invalid."]
  }
}

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "errors": {
      "amount": ["The amount field is required."]
    }
  }
}

HTTP/1.1 422 Unprocessable Entity

{
  "message": "The amount field is required. (and 1 more error)",
  "errors": {
    "amount": ["The amount field is required."],
    "debit_wallet": ["The debit wallet field is required."]
  }
}

{
  "status": "failed",
  "status_code": 422,
  "message": "Request failed.",
  "data": {
    "customer_name": ["The customer_name field contains a reserved word (test) and cannot be used."]
  }
}

{
  "status": "failed",
  "status_code": 422,
  "message": "The payload contains disallowed HTML or markup tags.",
  "data": {
    "error": {
      "note": ["The note field contains disallowed tags or markup."]
    }
  },
  "error": {
    "code": "invalid_argument",
    "message": "The payload contains disallowed HTML or markup tags.",
    "request_id": "req_..."
  }
}

{ "success": false, "message": "Deposit not found." }

{
  "status": "failed",
  "status_code": 402,
  "message": "Request failed.",
  "data": { "error": "Unable to charge your USDC balance." }
}

{
  "status": "failed",
  "status_code": 429,
  "message": "Request failed.",
  "data": { "error": "A wallet creation request for this currency is already in progress, please try again shortly" }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{ "message": "Too Many Attempts." }

{
  "status": "failed",
  "status_code": 400,
  "message": "Request failed.",
  "data": { "error": "Something went wrong, please try again later" }
}

async function callYativo(url, options = {}) {
  const res = await fetch(url, options);
  let body = null;
  try { body = await res.json(); } catch { /* empty or non-JSON body */ }

  const err = body?.error_details;
  if (res.ok && !err) {
    return {
      ok: true,
      httpStatus: res.status,
      data: body?.data ?? body,
      pagination: body?.pagination ?? null,
    };
  }

  return {
    ok: false,
    httpStatus: err?.http_status ?? res.status,
    code: err?.code ?? 'server_error',
    message: err?.message ?? `Request failed (HTTP ${res.status})`,
    fieldErrors: err?.fields ?? null, // { field: [messages] }; { error: [message] } when not field-specific
    retryable: err?.retryable ?? res.status >= 500,
    retryAfter: err?.retry_after ?? null,
  };
}

const r = await callYativo(`${BASE}/v1/wallet/payout`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': KEY,
    'X-Api-Secret': SECRET,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify(payload),
});

if (!r.ok) {
  switch (r.code) {
    case 'unauthenticated':  /* fix credentials */ break;
    case 'forbidden':        /* KYC, IP, permission or customer restriction: don't retry */ break;
    case 'conflict':         /* in progress or key reuse: check the outcome */ break;
    case 'validation_error': /* show r.fieldErrors next to the form fields */ break;
    case 'rate_limited':     /* wait r.retryAfter seconds, then retry */ break;
    default:
      if (r.httpStatus >= 500) { /* check the transaction state, then retry with backoff */ }
      else { /* bad_request, payment_required, not_found…: show r.message */ }
  }
}