İçeriğe geç
Apex Settlement

Hatalar

Hata zarfı, ona göre dallanma, ne zaman yeniden deneneceği ve en sık karşılaşılan kodlar.

Hata zarfı

İsteği neyin reddettiğinden bağımsız olarak her hata, 4xx ya da 5xx aralığında bir HTTP durumuyla aynı JSON gövdesini döner:

422 Unprocessable Entity
{
  "code": "quote_expired",
  "message": "the Quote has expired; ask for a new decision",
  "correlation_id": "b2d4f6a8-1c3e-4a5b-9d7f-0e2c4a6b8d1f"
}
AlanTürAnlamı
codestringKararlı, snake_case bir kod. Mantığınızı buna göre kurun.
messagestringİnsanlar için bir cümle, İngilizce. Değişebilir; asla ayrıştırmayın.
correlation_idstringİsteğin loglarımızdaki kimliği. X-Correlation-ID başlığında da bulunur. Destekle paylaşın.
detailsarrayvalidation_failed gibi bazı hatalarda bulunur: her sorun için bir {field, message}.

Koda göre dallanın

Ne yapacağınıza code alanına bakarak karar verin. HTTP durumu sorunun sınıfını, kod ise hangi sorun olduğunu söyler. Yeni kodlar eklenebilir; bilinmeyen bir kodu durumuna göre ele alan varsayılan bir dal bulundurun.

Node.js
const res = await fetch(url, options);
if (!res.ok) {
  const err = await res.json();
  switch (err.code) {
    case "quote_expired":
      return requote();
    case "rate_limited":
      return retryAfter(Number(res.headers.get("Retry-After") ?? "1"));
    default:
      throw new Error(`${res.status} ${err.code} (correlation ${err.correlation_id})`);
  }
}

Bir 5xx yanıtı nedeni message alanında hiçbir zaman taşımaz: internal error ya da genel bir durum metni yazar. Biliniyorsa code yine hatayı adlandırır (örneğin quote_unavailable); correlation_id de nedeni bulmamızı sağlar.

Doğrulama hataları

Alan kurallarına uymayan bir gövde, 400 ve validation_failed ile döner; her alan için, sizin gönderdiğiniz adıyla bir giriş içerir:

400 Bad Request
{
  "code": "validation_failed",
  "message": "request validation failed",
  "correlation_id": "9e1c3a5b-7d2f-4e8a-b6c4-1f3d5a7b9c2e",
  "details": [
    { "field": "beneficiary_id", "message": "failed on the 'uuid' rule" },
    { "field": "purpose", "message": "failed on the 'oneof' rule" }
  ]
}

Geçerli JSON olmayan ya da yanlış JSON türünde bir değer taşıyan gövde (örneğin metin yerine sayı olarak gönderilmiş bir tutar) 400 ve bad_request ile, ayrıntı olmadan döner.

Yeniden deneme

Ne olduNe yapmalı
429 rate_limitedRetry-After içindeki saniye kadar bekleyip yeniden deneyin.
500, 502, 503 ya da yanıtsız bir zaman aşımıÜstel artan bekleme ile yeniden deneyin. POST /v1/payouts ve POST /v1/end-customers için aynı Idempotency-Key ve aynı gövdeyi gönderin.
409 idempotency_in_progressAynı anahtarla gelen ilk istek hâlâ sürüyor. Bir iki saniye sonra yeniden deneyin.
422 quote_expiredYeni teklif isteyin ve birini kabul edin.
Diğer 4xx yanıtlarıİsteği düzeltin. Aynı isteği değiştirmeden göndermek aynı yanıtı verir.

Yukarıdaki iki istek dışındakiler Idempotency-Key almaz. Bunlardan birini zaman aşımından sonra yeniden denemeden önce, ilk denemenin gerçekleşip gerçekleşmediğini görmek için kaynağı okuyun. Bkz. Idempotency.

En sık karşılaşılan kodlar

DurumKodNe zaman
400validation_failedBir alan kurallarına uymuyor; details alanına bakın.
400bad_requestGövde geçerli JSON değil ya da bir değerin türü yanlış.
400invalid_idYoldaki bir kimlik UUID değil.
400idempotency_key_requiredPOST /v1/payouts ya da POST /v1/end-customers için Idempotency-Key gönderilmedi.
401unauthorizedKimlik bilgisi yok ya da gönderilen bir API anahtarı değil.
401api_key_invalidAnahtar bilinmiyor, bozuk, iptal edilmiş ya da diğer ortama ait.
401api_key_expiredAnahtarın süresi doldu.
401api_key_ip_deniedİstek, anahtarın izin vermediği bir adresten geldi.
403forbiddenAnahtarda bu uç noktanın istediği izin yok.
403customer_suspendedHesabınız askıya alındı; değişiklikler reddedilir, okumalar çalışır.
403customer_not_activeHesabınız etkin değil.
404not_foundBöyle bir uç nokta yok. Yöntemi ve yolu kontrol edin.
404payout_not_foundBu kimlikle size ait bir ödeme yok.
404beneficiary_not_foundBu kimlikle size ait bir alıcı yok.
409quote_already_usedBu teklif zaten bir ödemeye dönüştü. Ödemelerinizi okuyun ya da yeni teklif isteyin.
409payout_not_cancellableYalnızca accepted ya da awaiting_approval durumundaki bir ödeme iptal edilebilir.
409idempotency_in_progressAynı Idempotency-Key ile gelen bir istek hâlâ sürüyor.
409beneficiary_changedÖdediğiniz müşteri, tekliften sonra para alacağı hesabı değiştirdi. Yeniden teklif alın.
409beneficiary_unavailableAlıcıya şu an ödeme yapılamıyor.
422quote_expiredTeklifin expires_at zamanı geçti.
422quote_token_invalidquote_id size verilmiş bir teklif değil.
422idempotency_key_reusedIdempotency-Key farklı bir gövdeyle kullanılmış.
422bad_amountTutar pozitif bir ondalık metin değil.
422amount_scaleTutar, varlığının izin verdiğinden fazla ondalık taşıyor.
422beneficiary_not_verifiedAlıcı henüz doğrulanmadı.
422iban_invalidIBAN kontrol hanelerinden geçmiyor.
422beneficiary_fields_invalidHesap bilgileri, o hedefe giden hiçbir rotanın istemediği bir alan içeriyor.
422bad_cursor, bad_limit, unknown_stateBir liste sorgu parametresi hatalı.
422webhook_url_invalidURL herkese açık internette bir https adresi değil ya da kimlik bilgisi içeriyor.
429rate_limitedÇok fazla istek; Retry-After başlığına bakın.
500internal_errorBizim tarafımızda bir şey başarısız oldu. Artan bekleme ile yeniden deneyin.
502quote_unavailableBir Provider bir adımı şu an fiyatlayamadı. Kısa süre sonra yeniden sorun.
503service_unavailableBağlı olduğumuz bir servis kısa süreliğine erişilemiyor. Artan bekleme ile yeniden deneyin.

Tüm hata kodları

86 kod
KodHTTP durumuMesajİşlemler
bad_request400Bad Request
document_file_required400the upload must carry a file part named file
idempotency_key_invalid400Idempotency-Key must be between 1 and 128 characters
Tüm işlemler
idempotency_key_required400Idempotency-Key header is required
Tüm işlemler
invalid_id400id is not a UUID.
validation_failed400request validation failed
api_key_expired401the API key has expired
Tüm işlemler
api_key_invalid401the API key is not valid
Tüm işlemler
api_key_ip_denied401the API key may not be used from this address
Tüm işlemler
api_key_revoked401the API key has been revoked
Tüm işlemler
unauthorized401Unauthorized
Tüm işlemler
customer_not_active403the Customer cannot be used yet
Tüm işlemler
customer_suspended403the Customer is suspended; nothing can be changed until it is reactivated
Tüm işlemler
forbidden403Forbidden
Tüm işlemler
not_a_platform403only a Platform has End Customers
not_for_end_customers403an End Customer's Platform holds its API keys and webhook endpoints
Tüm işlemler
people_only403only a person can invite someone; an API key cannot
suspended_by_operator403the Operator suspended this End Customer; only the Operator can reactivate it
beneficiary_not_found404no Beneficiary under that id for the Customer
decision_not_found404The quote set behind quote_id no longer exists; ask for a new Quote.
document_not_found404no document under that id for the Customer
end_customer_not_found404no End Customer of yours under that id
payout_not_found404no Payout under that id
quote_not_found404the Decision Record holds no Quote for that Route Template
receiving_code_not_found404no Customer receives under that code
webhook_delivery_not_found404webhook delivery not found
webhook_endpoint_not_found404webhook endpoint not found
beneficiary_changed409the Beneficiary's account changed after the quote; quote again
beneficiary_unavailable409the Beneficiary cannot be paid now; its Customer has no account to receive into
customer_email_taken409a Customer of this Operating Entity already uses that email
idempotency_in_progress409a request with this Idempotency-Key is still being processed
Tüm işlemler
invalid_transition409İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin.
payout_not_cancellable409a Payout can be cancelled only before it is funded
profile_locked409İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin.
quote_already_used409this quote has already been accepted
receiving_account_missing409the Customer behind that code has no Receiving Account yet
terms_changed409the terms changed after they were read
terms_not_accepted409the terms have not been accepted
webhook_delivery_pending409the delivery is still being attempted
webhook_endpoint_state409the webhook endpoint is not in a state that allows this
document_too_large413a document may be at most 10 MB
payload_too_large413Request Entity Too Large
amount_scale422amount has more decimals than the asset settles at
asset_invalid422asset is required: an asset code of 2 to 10 capital letters or digits
bad_amount422amount is not a positive decimal number.
bad_cursor422the cursor is not one a Payout list answered
bad_limit422İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin.
beneficiary_fields_invalid422the Beneficiary carries details no Rail to that destination asks for
beneficiary_not_verified422the Beneficiary is not verified
country_mismatch422the address in the profile is not in the country this account was opened for
country_not_accepted422İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin.
customer_not_active422the Customer is not active
document_empty422the file is empty
document_kind_unknown422unknown document kind
document_limit_reached422the Customer holds as many documents as it may; versions are never deleted
document_subject_invalid422the document's subject does not fit its kind or the Customer
document_type_not_allowed422a document must be a PDF, JPEG or PNG file
iban_invalid422the IBAN does not check out
idempotency_key_reused422Idempotency-Key was already used with a different request
Tüm işlemler
linked_customer_not_active422a Beneficiary of the customer kind links an active Customer of the same Operating Entity
profile_invalid422the Compliance Profile is incomplete
profile_missing422save a Compliance Profile before submitting it
proof_required422an own account needs a proof of ownership before it is verified
quote_expired422the Quote has expired; ask for a new decision
quote_inconsistent422the Quote and the Route Template it names no longer agree
quote_token_invalid422the quote_id is not one this Customer was quoted
receiving_account_invalid422a Receiving Account is one of the Customer's own accounts that Compliance verified
unknown_state422İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin.
webhook_endpoint_limit422the Customer already has the most webhook endpoints it may register
webhook_event_unknown422an event type is not one a webhook endpoint can subscribe to
webhook_url_invalid422the url must be an https address on the public internet, without credentials
rate_limited429Too Many Requests
Tüm işlemler
internal_error500internal error
Tüm işlemler
bad_gateway502Bad Gateway
Tüm işlemler
policy_unavailable502internal error
prerequisites_unavailable502internal error
quote_unavailable502internal error
approval_rules_unavailable503internal error
beneficiaries_unavailable503internal error
customers_unavailable503internal error
document_busy503internal error
float_unavailable503internal error
funds_unavailable503internal error
pricing_unavailable503internal error
webhooks_unavailable503internal error

Bu sayfada