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:
{
"code": "quote_expired",
"message": "the Quote has expired; ask for a new decision",
"correlation_id": "b2d4f6a8-1c3e-4a5b-9d7f-0e2c4a6b8d1f"
}| Alan | Tür | Anlamı |
|---|---|---|
code | string | Kararlı, snake_case bir kod. Mantığınızı buna göre kurun. |
message | string | İnsanlar için bir cümle, İngilizce. Değişebilir; asla ayrıştırmayın. |
correlation_id | string | İsteğin loglarımızdaki kimliği. X-Correlation-ID başlığında da bulunur. Destekle paylaşın. |
details | array | validation_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.
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:
{
"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 oldu | Ne yapmalı |
|---|---|
429 rate_limited | Retry-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_progress | Aynı anahtarla gelen ilk istek hâlâ sürüyor. Bir iki saniye sonra yeniden deneyin. |
422 quote_expired | Yeni 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
| Durum | Kod | Ne zaman |
|---|---|---|
| 400 | validation_failed | Bir alan kurallarına uymuyor; details alanına bakın. |
| 400 | bad_request | Gövde geçerli JSON değil ya da bir değerin türü yanlış. |
| 400 | invalid_id | Yoldaki bir kimlik UUID değil. |
| 400 | idempotency_key_required | POST /v1/payouts ya da POST /v1/end-customers için Idempotency-Key gönderilmedi. |
| 401 | unauthorized | Kimlik bilgisi yok ya da gönderilen bir API anahtarı değil. |
| 401 | api_key_invalid | Anahtar bilinmiyor, bozuk, iptal edilmiş ya da diğer ortama ait. |
| 401 | api_key_expired | Anahtarın süresi doldu. |
| 401 | api_key_ip_denied | İstek, anahtarın izin vermediği bir adresten geldi. |
| 403 | forbidden | Anahtarda bu uç noktanın istediği izin yok. |
| 403 | customer_suspended | Hesabınız askıya alındı; değişiklikler reddedilir, okumalar çalışır. |
| 403 | customer_not_active | Hesabınız etkin değil. |
| 404 | not_found | Böyle bir uç nokta yok. Yöntemi ve yolu kontrol edin. |
| 404 | payout_not_found | Bu kimlikle size ait bir ödeme yok. |
| 404 | beneficiary_not_found | Bu kimlikle size ait bir alıcı yok. |
| 409 | quote_already_used | Bu teklif zaten bir ödemeye dönüştü. Ödemelerinizi okuyun ya da yeni teklif isteyin. |
| 409 | payout_not_cancellable | Yalnızca accepted ya da awaiting_approval durumundaki bir ödeme iptal edilebilir. |
| 409 | idempotency_in_progress | Aynı Idempotency-Key ile gelen bir istek hâlâ sürüyor. |
| 409 | beneficiary_changed | Ödediğiniz müşteri, tekliften sonra para alacağı hesabı değiştirdi. Yeniden teklif alın. |
| 409 | beneficiary_unavailable | Alıcıya şu an ödeme yapılamıyor. |
| 422 | quote_expired | Teklifin expires_at zamanı geçti. |
| 422 | quote_token_invalid | quote_id size verilmiş bir teklif değil. |
| 422 | idempotency_key_reused | Idempotency-Key farklı bir gövdeyle kullanılmış. |
| 422 | bad_amount | Tutar pozitif bir ondalık metin değil. |
| 422 | amount_scale | Tutar, varlığının izin verdiğinden fazla ondalık taşıyor. |
| 422 | beneficiary_not_verified | Alıcı henüz doğrulanmadı. |
| 422 | iban_invalid | IBAN kontrol hanelerinden geçmiyor. |
| 422 | beneficiary_fields_invalid | Hesap bilgileri, o hedefe giden hiçbir rotanın istemediği bir alan içeriyor. |
| 422 | bad_cursor, bad_limit, unknown_state | Bir liste sorgu parametresi hatalı. |
| 422 | webhook_url_invalid | URL herkese açık internette bir https adresi değil ya da kimlik bilgisi içeriyor. |
| 429 | rate_limited | Çok fazla istek; Retry-After başlığına bakın. |
| 500 | internal_error | Bizim tarafımızda bir şey başarısız oldu. Artan bekleme ile yeniden deneyin. |
| 502 | quote_unavailable | Bir Provider bir adımı şu an fiyatlayamadı. Kısa süre sonra yeniden sorun. |
| 503 | service_unavailable | Bağlı olduğumuz bir servis kısa süreliğine erişilemiyor. Artan bekleme ile yeniden deneyin. |
Tüm hata kodları
| Kod | HTTP durumu | Mesaj | İşlemler |
|---|---|---|---|
bad_request | 400 | Bad Request | |
document_file_required | 400 | the upload must carry a file part named file | |
idempotency_key_invalid | 400 | Idempotency-Key must be between 1 and 128 characters | Tüm işlemler |
idempotency_key_required | 400 | Idempotency-Key header is required | Tüm işlemler |
invalid_id | 400 | id is not a UUID. | |
validation_failed | 400 | request validation failed | |
api_key_expired | 401 | the API key has expired | Tüm işlemler |
api_key_invalid | 401 | the API key is not valid | Tüm işlemler |
api_key_ip_denied | 401 | the API key may not be used from this address | Tüm işlemler |
api_key_revoked | 401 | the API key has been revoked | Tüm işlemler |
unauthorized | 401 | Unauthorized | Tüm işlemler |
customer_not_active | 403 | the Customer cannot be used yet | Tüm işlemler |
customer_suspended | 403 | the Customer is suspended; nothing can be changed until it is reactivated | Tüm işlemler |
forbidden | 403 | Forbidden | Tüm işlemler |
not_a_platform | 403 | only a Platform has End Customers | |
not_for_end_customers | 403 | an End Customer's Platform holds its API keys and webhook endpoints | Tüm işlemler |
people_only | 403 | only a person can invite someone; an API key cannot | |
suspended_by_operator | 403 | the Operator suspended this End Customer; only the Operator can reactivate it | |
beneficiary_not_found | 404 | no Beneficiary under that id for the Customer | |
decision_not_found | 404 | The quote set behind quote_id no longer exists; ask for a new Quote. | |
document_not_found | 404 | no document under that id for the Customer | |
end_customer_not_found | 404 | no End Customer of yours under that id | listBalanceslistBeneficiariescreateBeneficiarylinkBeneficiarygetBeneficiarygetCustomerlistDepositInstructionslistDocumentsuploadDocumentdownloadDocumentlistEndCustomerscreateEndCustomergetEndCustomerreactivateEndCustomersuspendEndCustomerlistIncomingPayoutsgetIncomingPayoutgetOnboardinglistPayoutscreatePayoutgetPayoutcancelPayoutgetProfilesaveProfilesubmitProfilecreateQuotegetReceivingsetReceivingAccountissueReceivingCodegetTermsacceptTermslistWebhookEndpointscreateWebhookEndpointredeliverWebhooklistWebhookDeliveriesdisableWebhookEndpointenableWebhookEndpointrotateWebhookSecret |
payout_not_found | 404 | no Payout under that id | |
quote_not_found | 404 | the Decision Record holds no Quote for that Route Template | |
receiving_code_not_found | 404 | no Customer receives under that code | |
webhook_delivery_not_found | 404 | webhook delivery not found | |
webhook_endpoint_not_found | 404 | webhook endpoint not found | |
beneficiary_changed | 409 | the Beneficiary's account changed after the quote; quote again | |
beneficiary_unavailable | 409 | the Beneficiary cannot be paid now; its Customer has no account to receive into | |
customer_email_taken | 409 | a Customer of this Operating Entity already uses that email | |
idempotency_in_progress | 409 | a request with this Idempotency-Key is still being processed | Tüm işlemler |
invalid_transition | 409 | İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin. | |
payout_not_cancellable | 409 | a Payout can be cancelled only before it is funded | |
profile_locked | 409 | İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin. | |
quote_already_used | 409 | this quote has already been accepted | |
receiving_account_missing | 409 | the Customer behind that code has no Receiving Account yet | |
terms_changed | 409 | the terms changed after they were read | |
terms_not_accepted | 409 | the terms have not been accepted | |
webhook_delivery_pending | 409 | the delivery is still being attempted | |
webhook_endpoint_state | 409 | the webhook endpoint is not in a state that allows this | |
document_too_large | 413 | a document may be at most 10 MB | |
payload_too_large | 413 | Request Entity Too Large | |
amount_scale | 422 | amount has more decimals than the asset settles at | |
asset_invalid | 422 | asset is required: an asset code of 2 to 10 capital letters or digits | |
bad_amount | 422 | amount is not a positive decimal number. | |
bad_cursor | 422 | the cursor is not one a Payout list answered | |
bad_limit | 422 | İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin. | |
beneficiary_fields_invalid | 422 | the Beneficiary carries details no Rail to that destination asks for | |
beneficiary_not_verified | 422 | the Beneficiary is not verified | |
cannot_link_self | 422 | that is the Customer's own Receiving Code | |
country_mismatch | 422 | the address in the profile is not in the country this account was opened for | |
country_not_accepted | 422 | İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin. | |
customer_not_active | 422 | the Customer is not active | |
document_empty | 422 | the file is empty | |
document_kind_unknown | 422 | unknown document kind | |
document_limit_reached | 422 | the Customer holds as many documents as it may; versions are never deleted | |
document_subject_invalid | 422 | the document's subject does not fit its kind or the Customer | |
document_type_not_allowed | 422 | a document must be a PDF, JPEG or PNG file | |
iban_invalid | 422 | the IBAN does not check out | |
idempotency_key_reused | 422 | Idempotency-Key was already used with a different request | Tüm işlemler |
linked_customer_not_active | 422 | a Beneficiary of the customer kind links an active Customer of the same Operating Entity | |
profile_invalid | 422 | the Compliance Profile is incomplete | |
profile_missing | 422 | save a Compliance Profile before submitting it | |
proof_required | 422 | an own account needs a proof of ownership before it is verified | |
quote_expired | 422 | the Quote has expired; ask for a new decision | |
quote_inconsistent | 422 | the Quote and the Route Template it names no longer agree | |
quote_token_invalid | 422 | the quote_id is not one this Customer was quoted | |
receiving_account_invalid | 422 | a Receiving Account is one of the Customer's own accounts that Compliance verified | |
unknown_state | 422 | İşleme göre değişir; anlamını görmek için bir işlemin üzerine gelin. | |
webhook_endpoint_limit | 422 | the Customer already has the most webhook endpoints it may register | |
webhook_event_unknown | 422 | an event type is not one a webhook endpoint can subscribe to | |
webhook_url_invalid | 422 | the url must be an https address on the public internet, without credentials | |
rate_limited | 429 | Too Many Requests | Tüm işlemler |
internal_error | 500 | internal error | Tüm işlemler |
bad_gateway | 502 | Bad Gateway | Tüm işlemler |
policy_unavailable | 502 | internal error | |
prerequisites_unavailable | 502 | internal error | |
quote_unavailable | 502 | internal error | |
approval_rules_unavailable | 503 | internal error | |
beneficiaries_unavailable | 503 | internal error | |
customers_unavailable | 503 | internal error | |
document_busy | 503 | internal error | |
float_unavailable | 503 | internal error | |
funds_unavailable | 503 | internal error | |
pricing_unavailable | 503 | internal error | |
webhooks_unavailable | 503 | internal error |