Error Handling

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

{
  "type": "https://doc.connectpsp.com/errors/duplicated-external-reference",
  "title": "Referência Externa Duplicada",
  "status": 409,
  "code": "DUPLICATED_EXTERNAL_REFERENCE",
  "detail": "Já existe uma operação com o externalReference informado: withdraw_xyz789."
}

{
  "type": "https://doc.connectpsp.com/errors/unauthorized",
  "title": "ApplicationToken Inválido",
  "status": 401,
  "detail": "O ApplicationToken fornecido não foi encontrado ou está inativo."
}

async function createCashOut(payload, idempotencyKey) {
  const response = await fetch('https://api.homologacao.connectpsp.com/cash-out', {
    method: 'POST',
    headers: {
      /* Authorization, ApplicationToken, DigitalSignature, Content-Type ... */
      'X-Idempotency-Key': idempotencyKey, // optional, recommended: reuse it only to retry this same request
    },
    body: JSON.stringify(payload)
  });

  if (response.status === 401 && response.headers.get('WWW-Authenticate')) {
    // JWT missing, invalid or expired: no body. Get a new token and retry.
    await refreshToken();
    return createCashOut(payload, idempotencyKey);
  }

  if (!response.ok) {
    const error = await response.json();

    switch (error.code) {
      case 'DUPLICATED_EXTERNAL_REFERENCE':
        // A Cash-Out with this externalReference already exists: GET /cash-out/{id}
        // accepts the externalReference, so fetch it and follow its status.
        return getCashOut(payload.externalReference);

      case 'IDEMPOTENCY_KEY_IN_PROGRESS':
        // The first attempt with this key is still running. Wait and check it.
        await sleep(2000);
        return getCashOut(payload.externalReference);

      case 'IDEMPOTENCY_KEY_REUSED':
        // Bug on our side: the same key was used for a different body.
        throw new Error('X-Idempotency-Key reused with a different payload.');

      case 'VALIDATION_ERROR':
        throw new Error(`Invalid Cash-Out request: ${error.detail}`);

      default:
        // Log and escalate unknown errors
        logger.error('ConnectPSP error', error);
        throw new Error(error.detail);
    }
  }

  // 202 Accepted: queued, NOT paid. The outcome arrives by webhook.
  return response.json();
}

function onCashOutEvent(event) {
  const { status, failure, reason } = event.data;

  switch (event.eventType) {
    case 'CASHOUT_COMPLETED':
      // status === 'COMPLETED'
      return markPaid(event.data);

    case 'CASHOUT_FAILED':
      // status === 'CANCELLED': the money never left your account
      switch (failure.code) {
        case 'INSUFFICIENT_FUNDS':
          return triggerRebalanceAlert(event.data);
        case 'PIX_KEY_NOT_FOUND':
        case 'PIX_KEY_INVALID':
          return askUserForAnotherKey(event.data);
        default:
          return markCancelled(event.data, failure.code, failure.message);
      }

    case 'CASHOUT_REFUNDED':
      // status === 'REFUNDED': paid, then returned to your account
      return markRefunded(event.data, reason);
  }
}