Hata Yönetimi

API standart HTTP durum kodları kullanır. Başarılı yanıtlar kaynak gövdesini doğrudan döndürür. Hatalar, HTTP API'leri için RFC 9457 Problem Details biçimini (application/problem+json) iki genişletme üyesiyle izler: programatik olarak switch'leyeceğiniz üst düzey bir code ve tek alanlı doğrulama hatalarında üst düzey bir field (snake_case). Birden fazla alan aynı anda başarısız olduğunda field, alan bazlı dökümü taşıyan bir errors[] dizisiyle (bir Paymos genişletme üyesi, §3.2) değiştirilir.

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Her hata yanıtı, HTTP API'leri için RFC 9457 Problem Details biçimini izler ve Content-Type: application/problem+json olarak servis edilir.

Tek hata (çoğu yanıt)

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Çok alanlı doğrulama

Yalnızca birden fazla alan aynı anda doğrulamayı geçemediğinde üretilir. Üst düzey code her zaman validation_failed'dır; alan bazlı ayrıntı errors[] içinde yaşar:

{
  "type": "https://paymos.io/docs/errors/codes#validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    { "code": "field_required", "field": "currency", "message": "Currency is required." },
    { "code": "field_must_be_positive", "field": "amount", "message": "Amount must be > 0." }
  ]
}

Alan referansı

Neden yapılandırılmış kodlar (sadece message değil)

message ve detail metni sürümler arasında evrilebilir, yerelleştirilebilir veya bağlamla genişletilebilir. code kararlı sözleşmedir — bir kod yayınlandıktan sonra anlamı asla değişmez. Programatik işleme ve yerelleştirme için code üzerinden switch yapın.

import { RateLimitError, ValidationError } from '@paymos/sdk';

try {
  await paymos.withdrawals.create(request);
} catch (error) {
  if (error instanceof ValidationError) {
    for (const item of error.errors) highlight(item.field, item.message);
  } else if (error instanceof RateLimitError) {
    scheduleRetry(error.retryAfterSeconds);
  }
  throw error;
}

use paymos::{ApiErrorKind, Error};

match paymos.withdrawals().create(&request).await {
    Ok(withdrawal) => process(withdrawal),
    Err(Error::Api(error)) if error.kind == ApiErrorKind::Validation => {
        for item in &error.errors {
            highlight(item.field.as_deref(), &item.message);
        }
    }
    Err(Error::Api(error)) if error.kind == ApiErrorKind::RateLimit => {
        schedule_retry(error.retry_after);
    }
    Err(error) => return Err(error),
}

Hata türleri

Her durum, bir title ve makine tarafından okunabilir bir code ile hata zarfında gelir. Tek bir durum birden fazla senaryoyu kapsayabilir — duruma değil, code değerine göre dallanın.

İstemci mantığını yönlendirmek için her zaman code değerini kullanın (HTTP durumunu değil) — birden fazla farklı iş senaryosu aynı HTTP durumunu paylaşır ve kablo kodu bunları birbirinden ayırır.

Rate limit'ler

API, varsayılan olarak işyeri başına saniyede 30 isteğe izin verir; POST /v1/invoices üzerinde daha sıkı bir limit vardır (5 istek/sn). Limitler işyeri başına, bir saniyelik pencerede sayılır — elinizdeki her API anahtarı aynı bütçeyi kullanır — ve ikisi de işyeri bazında yapılandırılabilir. Limit aşıldığında, Retry-After: 1 başlığıyla bir 429 Too Many Requests yanıtı alırsınız.

{
  "type": "https://paymos.io/docs/errors/codes#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded (30 req/sec). Retry after 1 second.",
  "code": "rate_limited"
}