Żbalji u rkupru

Uża kodiċijiet stabbli tal-iżbalji biex tiddeċiedi jekk tikkoreġix, tistenniex jew terġax tipprova.

X’għandek tagħmel

Ibbaża l-loġika fuq l-istatus HTTP u error.code, mhux fuq error.message miktub għall-bniedem.
401 jeħtieġ awtentikazzjoni valida; 403 jeħtieġ bidla fl-aċċess jew fil-pjan; 409 jeħtieġ verifika tal-operazzjoni f’kunflitt jew tal-verżjoni tar-riżorsa.

Aċċess miċħud u tentattivi mill-ġdid

401: 401 mhux dejjem ifisser li t-token skada. Jekk skada, ikseb wieħed ġdid u erġa’ pprova l-qari darba biss. Jekk il-kisba tat-token tagħti 401, iċċekkja ċ-ċavetta u waqqaf it-tentattivi awtomatiċi.
403: Għal 403, iċċekkja l-permessi, ir-restrizzjonijiet IP u l-pjan. Token ġdid ma jirrestawrax aċċess revokat.

Awtentikazzjoni

Politika ta’ tentattivi mill-ġdid

Għal ħsarat temporanji, uża numru limitat ta’ tentattivi b’stennija li tiżdied u dewmien każwali.
Irrispetta Retry-After meta jingħata.
Jekk kitba tiskadi, ir-riżultat tagħha jista’ ma jkunx magħruf: żomm l-istess Idempotency-Key u talba mhux mibdula meta terġa’ tipprova l-istess operazzjoni loġika.
Il-katalgu hawn taħt jispjega kull kodiċi ta’ żball ippubblikat.

Kitbiet siguri

Limiti tar-rata

422 / 409

Għall-prezzijiet, format tal-munita jew preċiżjoni tal-ammont mhux validi jirritornaw 422 request.validation_failed.
Kodiċi tal-munita validu li ma jaqbilx mal-lista tal-prezzijiet magħżula jirritorna 409 resource.version_conflict.
Iċċekkja l-kuntest u l-verżjonijiet qabel terġa’ tipprova.

Katalgu tal-iżbalji

400request.malformedIt-talba ma tistax tiġi analizzata.

X’għandek tagħmel: Iċċekkja s-sintassi JSON, il-kodifikazzjoni tal-URL u l-istruttura tat-talba.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li tikkoreġi t-talba.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsIċ-ċavetta API jew it-token ta’ aċċess huwa invalidu, skadut jew revokat.

X’għandek tagħmel: Iċċekkja l-URL tal-ħanut u l-kredenzjal. Ikseb token ġdid b’ċavetta API attiva.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li tikkoreġi l-awtentikazzjoni; evita talbiet ripetuti b’token invalidu.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredIl-header Authorization meħtieġ huwa nieqes jew l-iskema tiegħu mhijiex korretta.

X’għandek tagħmel: Uża ApiKey meta titlob token u Bearer għall-operazzjonijiet tar-riżorsi.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li tipprovdi l-header korrett.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedIs-servizz ma setax jistabbilixxi indirizz IP affidabbli tal-klijent.

X’għandek tagħmel: Staqsi lill-operatur tal-ħanut biex jiċċekkja l-mogħdija tad-dħul. Iddaħħalx headers ta’ trażmissjoni int stess.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li l-mogħdija ta’ konnessjoni affidabbli tiġi restawrata.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedL-indirizz IP tas-sors mhuwiex fil-lista ta’ indirizzi permessi taċ-ċavetta.

X’għandek tagħmel: Uża indirizz tas-sors approvat jew staqsi lil amministratur awtorizzat biex jeditja l-lista IP taċ-ċavetta.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova biss wara li l-indirizz ikun permess.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedIċ-ċavetta m’għandhiex permess effettiv meħtieġ għal din l-operazzjoni.

X’għandek tagħmel: Iċċekkja l-permessi meħtieġa u kondizzjonali tal-operazzjoni, il-permessi taċ-ċavetta u l-aċċess tal-persuna li ħarġitha.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li amministratur awtorizzat jagħti l-aċċess meħtieġ.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledL-aċċess API huwa diżattivat għal dan il-ħanut.

X’għandek tagħmel: Staqsi lis-sid tal-ħanut biex jiċċekkja l-pjan attiv u d-disponibbiltà tal-API.
Politika ta’ tentattivi mill-ġdid: Terġax tipprova sakemm l-aċċess API jiġi attivat.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededIl-bidla taqbeż limitu tal-pjan attwali.

X’għandek tagħmel: Iċċekkja l-limitu tar-riżorsa applikabbli u aġġusta l-bidla jew il-pjan.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li ssolvi l-limitu; uża ċavetta ta’ idempotenza ġdida jekk it-talba tinbidel.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledIl-pjan attwali ma jinkludix din l-operazzjoni.

X’għandek tagħmel: Iċċekkja l-pjan minimu muri għall-operazzjoni.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li l-pjan jippermetti l-operazzjoni u ċ-ċavetta jkollha l-permessi meħtieġa.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedLimitu tal-pjan jimblokka din ir-riżorsa partikolari.

X’għandek tagħmel: Staqsi lis-sid biex isolvi r-restrizzjoni tal-pjan tar-riżorsa.
Politika ta’ tentattivi mill-ġdid: Tirrepetix l-istess talba waqt li r-riżorsa tibqa’ mblukkata.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundIr-riżorsa hija nieqsa, imħassra jew mhux disponibbli taħt l-identifikatur mogħti.

X’għandek tagħmel: Iċċekkja l-ħanut, il-mogħdija tar-riżorsa u l-identifikatur. Uża identifikaturi mogħtija minn dan il-ħanut.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova biss wara li tikkoreġi l-mira jew tikkonferma li teżisti.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedL-endpoint ma jappoġġax dan il-metodu HTTP.

X’għandek tagħmel: Uża l-metodu dokumentat; il-header Allow jidentifika l-metodi appoġġati.
Politika ta’ tentattivi mill-ġdid: Terġax tipprova l-metodu mhux appoġġat.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedDin iċ-ċavetta ta’ idempotenza tappartjeni għal talba differenti.

X’għandek tagħmel: Sib l-operazzjoni oriġinali. Uża ċavetta ġdida biss għal operazzjoni loġika intenzjonalment ġdida.
Politika ta’ tentattivi mill-ġdid: Terġax tipprova kontenut mibdul biċ-ċavetta f’kunflitt.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsValur uniku jikkonfliġġi ma’ riżorsa eżistenti.

X’għandek tagħmel: Aqra r-riżorsa eżistenti u ddeċiedi jekk tużahiex jew tagħżilx valur uniku differenti.
Politika ta’ tentattivi mill-ġdid: Tirrepetix l-istess ħolqien f’kunflitt.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useRiżorsi oħra għadhom jiddependu fuq din ir-riżorsa.

X’għandek tagħmel: Irrevedi d-dipendenzi u neħħihom jew ibdilhom permezz ta’ operazzjonijiet appoġġati qabel it-tħassir.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li ssolvi d-dipendenzi.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictL-istat attwali tan-negozju jipprevjeni din il-bidla.

X’għandek tagħmel: Aqra l-istat attwali u agħżel tranżizzjoni valida tan-negozju.
Politika ta’ tentattivi mill-ġdid: Tisforzax awtomatikament u tissottomettix ripetutament il-bidla f’kunflitt.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictKitba oħra biddlet ir-riżorsa wara l-verżjoni li qrajt.

X’għandek tagħmel: Aqra l-istat l-aktar reċenti, irrikonċilja l-bidla u ssottometti expected_version ġdid.
Politika ta’ tentattivi mill-ġdid: Uża ċavetta ta’ idempotenza ġdida għall-operazzjoni riveduta; tiktebx fuq id-data mingħajr verifika.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeIt-talba taqbeż il-limitu tad-daqs.

X’għandek tagħmel: Naqqas il-kontenut jew aqsam ix-xogħol f’operazzjonijiet individwali appoġġati.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova operazzjonijiet iżgħar u validi biċ-ċwievet ta’ idempotenza tagħhom stess.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeIt-tip tal-midja jew il-kodifikazzjoni tal-kontenut mhuwiex appoġġat.

X’għandek tagħmel: Għal kitbiet JSON, uża Content-Type: application/json u kontenut appoġġat mhux ikkompressat.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova wara li tikkoreġi t-tip tal-midja jew il-kodifikazzjoni.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedQasam jew parametru wieħed jew aktar ma jgħaddix mill-validazzjoni.

X’għandek tagħmel: Iċċekkja error.fields, imbagħad l-oqsma obbligatorji, il-permess għal null, l-identifikaturi u l-valuri permessi.
Politika ta’ tentattivi mill-ġdid: Erġa’ pprova talba kkoreġuta; kitba mibdula hija operazzjoni loġika ġdida.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullIl-kju qasir tal-API huwa mimli; l-eżekuzzjoni tat-talba għadha ma bdietx.

X’għandek tagħmel: Poġġi t-talbiet f’kju u rrispetta l-header Retry-After tat-tweġiba.
Politika ta’ tentattivi mill-ġdid: Stenna mill-inqas Retry-After sekondi u żid dewmien każwali. Żomm iċ-ċavetta u l-kontenut oriġinali meta terġa’ tipprova kitba.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutSkada l-ħin ta’ stennija fil-kju tal-API; l-eżekuzzjoni tat-talba għadha ma bdietx.

X’għandek tagħmel: Poġġi t-talbiet f’kju u rrispetta l-header Retry-After tat-tweġiba.
Politika ta’ tentattivi mill-ġdid: Stenna mill-inqas Retry-After sekondi u żid dewmien każwali. Żomm iċ-ċavetta u l-kontenut oriġinali meta terġa’ tipprova kitba.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededIr-rata tat-talbiet taqbeż il-limitu applikabbli.

X’għandek tagħmel: Poġġi t-talbiet f’kju u rrispetta l-header Retry-After tat-tweġiba.
Politika ta’ tentattivi mill-ġdid: Stenna mill-inqas Retry-After sekondi u żid dewmien każwali. Żomm iċ-ċavetta u l-kontenut oriġinali meta terġa’ tipprova kitba.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorSeħħ żball mhux mistenni tas-servizz.

X’għandek tagħmel: Irreġistra l-identifikatur tat-talba u kkuntattja lill-operatur jekk l-iżball jippersisti; teskludi l-kredenzjali mir-reġistri.
Politika ta’ tentattivi mill-ġdid: Uża tentattivi limitati b’dewmien li jiżdied. Għal kitba, żomm iċ-ċavetta ta’ idempotenza oriġinali u l-kontenut mhux mibdul.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseIl-gateway ma rċeviex tweġiba API valida.

X’għandek tagħmel: Żomm l-identifikatur tat-talba. Tweġiba falluta ma tipprovax li l-kitba ma ġietx applikata.
Politika ta’ tentattivi mill-ġdid: Uża tentattivi limitati b’dewmien li jiżdied; irrepeti l-istess kitba loġika bl-Idempotency-Key u l-kontenut oriġinali tagħha.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableL-API temporanjament ma jistax jipproċessa t-talba.

X’għandek tagħmel: Irrispetta Retry-After meta jkun preżenti u żomm l-identifikatur tat-talba jekk il-qtugħ jippersisti.
Politika ta’ tentattivi mill-ġdid: Uża tentattivi limitati b’dewmien li jiżdied u każwali; żomm iċ-ċavetta u l-kontenut meta terġa’ tipprova l-istess kitba.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutIl-gateway skada waqt li kien qed jistenna l-API.

X’għandek tagħmel: Żomm l-identifikatur tat-talba u ittratta r-riżultat tal-kitba bħala mhux magħruf.
Politika ta’ tentattivi mill-ġdid: Uża tentattivi limitati b’dewmien li jiżdied; għal kitba erġa’ uża ċ-ċavetta ta’ idempotenza oriġinali u l-kontenut mhux mibdul.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}