Hatalar

Hatalar problem details (RFC 9457) gövdeleridir. Çoğu application/problem+json, birkaçı application/json olarak gelir: gövdeyi içerik türüne göre değil, biçimine göre okuyun.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Integration.IdempotencyKeyRequired",
  "status": 400,
  "detail": "Send an X-Idempotency-Key header (1 to 128 characters) with every write: create, update, cancel and upload.",
  "code": "Integration.IdempotencyKeyRequired"
}

• Sözleşme code alanıdır. Programınız ona bakmalı. v1 içinde kararlıdır.
• detail insanlar içindir. Gösterin ya da kaydedin ama ayrıştırmayın: ifadesi değişebilir ve platform genelindeki birkaç ret (örneğin Company.Suspended) isteğin Accept-Language başlığındaki dilde yazılır.
• args, reddin neyle ilgili olduğunu söyler, söylenecek tek bir şey varsa: güncellemedeki alan (args.field), metadata anahtarı (args.key), verilmiş talebin anlaşması (args.dealId, üst düzeyde dealId olarak da).
• Bir hata gövdesi burada gösterilenden fazla alan taşıyabilir. Bilmediklerinizi yok sayın.

Tek istisna belirteç adresidir: RFC 6749’un istediği gibi OAuth hataları döner ({ "error": "...", "error_description": "..." }). Bkz. Kimlik doğrulama.

Doğrulama hataları

Alanlar doğrulamadan geçemezse yanıt 422 olur ve errors nesnesi, alanın gövdenizdeki yolu ile anahtarlanır:

{
  "title": "Validation Error",
  "status": 422,
  "detail": "...",
  "errors": {
    "origin.countryCode": ["..."],
    "transportMode": ["Unknown value 'Truck'. Expected one of: Road, Sea, Air, Rail, Multimodal, HandCarry."]
  }
}

Alanlar, uygulamada açılan bir taleple aynı kurallarla denetlenir. transportMode, modePolicy ve incoterm gibi metin değerleri adlarıyla, büyük küçük harf fark etmeden eşleşir; bunlar için sayı hiçbir zaman kabul edilmez.

Durum kodları

Durum	Anlamı	Ne yapmalı
400	İstek eksik ya da bir kurala uymuyor: X-Idempotency-Key yok (Integration.IdempotencyKeyRequired), externalReference yok (Integration.ExternalReferenceRequired), anlaşma filtrelerinden hiçbiri ya da ikisi birden (Integration.DealFilterRequired), JSON nesnesi olmayan bir güncelleme gövdesi (Integration.InvalidBody), bilinmeyen ya da salt okunur bir alan (Integration.UnknownField, Integration.FieldNotUpdatable), silinemeyen bir alanı temizleme (Integration.FieldNotClearable), metadata sınırı (Integration.MetadataInvalid), U+0000 gibi bir denetim karakteri içeren metin (alanı gösteren Integration.InvalidBody, anahtarı gösteren Integration.MetadataInvalid), dosyası ya da kategorisi olmayan yükleme (Document.FileRequired, Document.InvalidCategory), uygulamanın anlaşmanın bu aşamasında tarafınıza sunmadığı bir kategori (Document.CategoryNotOffered, args.offered ile) veya bir iş kuralı reddi.	code, detail ve args alanını okuyup isteği düzeltin.
401	Geçerli anahtar ya da belirteç yok (Integration.Unauthorized). Neden hiçbir zaman söylenmez.	Anahtarı, bitişini ve çıkış adresinizi kontrol edin; belirtecin süresi dolduysa yenisini alın. Sahip ya da Yöneticiniz çağrıyı çağrı kaydında görür.
403	Kimlik doğru ama izin yok: kapsam eksik (Integration.Forbidden), anahtar şu an kullanılamıyor (Integration.AccessDenied), şirket hesabı durdurulmuş (Company.Suspended), gönderici olmayan bir şirket talep açmaya çalışıyor (Company.WrongSegment) ya da canlı anahtarla deneme alanı rotası (Integration.SandboxOnly).	Anahtarın kapsamlarını ve modunu kontrol edin. Sürerse Sahip ya da Yöneticinize sorun.
404	Bulunamadı: kayıt yok, şirketiniz taraf değil ya da kayıt diğer moda (canlı ya da test) ait. Anlaşmanın operasyonu, anlaşma başlayana kadar 404 (Tracking.NotFound) döner.	Kimliği ve anahtarın modunu kontrol edin.
409	Çakışma: externalReference zaten kullanılmış (Integration.DuplicateExternalReference, requestId ile), aynı idempotency anahtarlı çağrı hâlâ işleniyor (Retry-After: 1), talep bu durumda değişemez (ShipmentRequest.InvalidTransition), talep verilmiş ve anlaşma olmuş (Integration.RequestAwarded, dealId ile), talep API’den değil uygulamada açılmış (Integration.RequestNotCreatedViaApi), anlaşmadan çekilinmiş ve belge alınmıyor (Document.DealNotOpen), göndericinin belgeleri onaylanmadan taşıyıcının taşıma belgesi (Document.BillOfLadingTooEarly), deneme alanında sırası gelmemiş adım (Integration.SandboxTransition), deneme belgesinin indirilmesi (Integration.SandboxFileNotKept) ya da henüz temiz taranmamış belge (Document.NotClean).	Mükerrerde dönen requestId’yi kullanın. İşlenen çağrıda bir saniye sonra aynı anahtarla tekrarlayın. Durum çakışmasında talebi okuyun; bkz. Güncelleme ve iptal. Belgede daha sonra yeniden deneyin.
412	If-Match talebin güncel ETag değerine uymuyor: talep siz okuduktan sonra değişti (Integration.PreconditionFailed). Hiçbir şey yazılmadı. Yanıt tekrar için saklanmaz.	Talebi yeniden okuyun, değişikliği gözden geçirip yeni ETag ile tekrar gönderin (aynı X-Idempotency-Key olur).
413	Yüklenen dosya 25 MB’tan büyük (Document.PayloadTooLarge) ya da güncelleme gövdesi 64 KB’tan büyük (Integration.BodyTooLarge, args.limitBytes ile).	Daha küçük bir dosya ya da gövde gönderin.
415	Yüklemenin türü izinli değil ya da içeriği bildirilen türe uymuyor (Document.UnsupportedMediaType): örneğin DOCX ya da XLSX diye bildirilen ama Word ya da Excel paketi olmayan bir arşiv.	PDF, JPEG, PNG, DOCX ya da XLSX gönderin; türünü doğru bildirin.
422	Doğrulama başarısız: errors her alanın nedenlerini listeler. Ya da yüklenen dosya virüs taramasından geçemedi (Document.Infected) ve saklanmadı. Ya da X-Idempotency-Key bu rotada başka bir istek için kullanılmış (Integration.IdempotencyKeyReused); hiçbir şey çalışmadı.	Alanları düzeltip yeni bir X-Idempotency-Key ile gönderin. Virüslü dosyayı asla tekrar göndermeyin. Kullanılmış anahtarda yeni isteği yeni anahtarla gönderin.
429	Hız sınırına, şirketin günlük yükleme hakkına (Integration.DailyUploadLimit) ya da anahtarın yeni idempotency anahtarları için günlük hakkına (Idempotency.DailyLimit, hiçbir şey çalışmadı) ulaşıldı. Yanıt tekrar için saklanmaz.	Retry-After varsa o kadar saniye, yoksa birkaç saniye bekleyin; tekrarlarda aralığı artırın, aynı X-Idempotency-Key olur. Bkz. Hız sınırları.
5xx	Bizim tarafımızda geçici bir sorun; örneğin yüklemenin deposu (Document.StorageFailed, 502), virüs tarayıcısı (Document.ScanUnavailable, 503) ya da bir değişikliğin taşıyıcı tarafı (ShipmentRequest.AmendmentNotDelivered, 503, hiçbir şey uygulanmadı). Yanıt tekrar için saklanmaz.	Aynı X-Idempotency-Key ve externalReference ile tekrar deneyin. Talep oluştuysa onu geri alırsınız, asla ikincisi açılmaz.

Kodlar

Kod	Durum
Integration.Unauthorized	401
Integration.Forbidden	403
Integration.AccessDenied	403
Integration.SandboxOnly	403
Company.Suspended	403
Company.WrongSegment	403
Integration.IdempotencyKeyRequired	400
Integration.ExternalReferenceRequired	400
Integration.DealFilterRequired	400
Integration.InvalidBody	400
Integration.UnknownField	400
Integration.FieldNotUpdatable	400
Integration.FieldNotClearable	400
Integration.MetadataInvalid	400
Document.FileRequired	400
Document.InvalidCategory	400
Document.CategoryNotOffered	400
Document.LoadingInstructionShipperOnly	400
ShipmentRequest.NotFound	404
Deal.NotFound	404
Tracking.NotFound	404
Document.NotFound	404
Integration.DuplicateExternalReference	409
Integration.SandboxTransition	409
Document.NotClean	409
ShipmentRequest.InvalidTransition	409
Integration.RequestNotCreatedViaApi	409
Integration.RequestAwarded	409
Document.DealNotOpen	409
Document.BillOfLadingTooEarly	409
Integration.SandboxFileNotKept	409
Integration.PreconditionFailed	412
Document.PayloadTooLarge	413
Integration.BodyTooLarge	413
Document.UnsupportedMediaType	415
Document.Infected	422
Integration.IdempotencyKeyReused	422
Integration.DailyUploadLimit	429
Idempotency.DailyLimit	429
Document.StorageFailed	502
Document.ScanUnavailable	503
ShipmentRequest.AmendmentNotDelivered	503

Diğer 400 kodları platformun kendi iş kurallarından gelir. v1 içinde yeni kodlar eklenebilir; bilmediğiniz bir kodu HTTP durumuna göre ele alın.

Yayınlama retleri hata değildir

Yayınlama izni olmayan bir "publish": true oluşturması yine başarılı olur: talep taslak olarak açılır ve 201 yanıtındaki publish.refusalCode ile publish.refusalDetail nedenini söyler (örneğin PageAccess.ApprovalRequired). Talebi uygulamada bir kişi yayınlayabilir.