Fel

Felkroppen

Ett misslyckat anrop svarar med en HTTP-statuskod och, i de flesta fall, den här JSON-kroppen:

{
  "error": "Access denied. You do not have permission to perform this action.",
  "code": "FORBIDDEN",
  "module": "apps",
  "correlationId": "3f2b9c1e-6d4a-4e0b-9a51-2c7d8e0f4b6a",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Ett fält utan värde utelämnas eller skickas som null. Ett fel från en äldre modul kan sakna code och module. Vissa koder lägger till egna fält; kodens avsnitt i referensen listar dem. Ange correlationId när du rapporterar ett problem.

Fel i problemformatet

Vissa rutter svarar i stället i standardformatet för problem, med innehållstypen application/problem+json. Det gör bland andra filrutterna för appar och containerinstanser och rutterna för ögonblicksbilder:

{
  "type": "…",
  "title": "backups-not-configured",
  "status": 422,
  "detail": "Backups are not enabled on PostgreSQL cluster 'orders', so there is no archive to snapshot into.",
  "code": "backups-not-configured",
  "remediation": "Enable backups in the cluster's Configuration, wait for the first archive, then snapshot.",
  "module": "db-postgres",
  "correlationId": "3f2b9c1e-6d4a-4e0b-9a51-2c7d8e0f4b6a"
}

Den här kroppen har inget fält error. Meningen för människor står i detail, som vissa koder lämnar tomt, och title är antingen en kort sammanfattning eller själva koden. code, module och correlationId betyder samma sak som ovan.

En klient som läser error när det finns, och annars detail och sedan title, hittar en mening att visa för varje fel.

Statuskoder

Slå upp en kod

En kod dokumenteras av modulen som äger den. Koder som betyder samma sak oavsett vilken modul som svarar dokumenteras en gång, under plattformens kärna (kernel), trots att kroppens module anger modulen som svarade: ett filfel från en app har "module": "apps", och dess kod finns på Fel vid filåtkomst. En moduls egna koder finns på modulens sidor.

Slå därför först upp en kod med paret module och code, och om den modulen inte dokumenterar koden, med kernel och koden. Plattformens dokumentationstjänst svarar på GET /docs-hub/errors/{module}/{code} för ett exakt par; den provar inte kernel åt dig.

Koderna som dokumenteras under kärnan finns på tre sidor:

• Felkoder — koderna som alla moduler kan svara med, och kärnans egna
• Fel vid filåtkomst — filrutterna för appar och containerinstanser
• Fel vid ögonblicksbilder — varför en ögonblicksbild eller återställning av ett PostgreSQL-kluster, en SQL Server-instans eller en containerinstans avvisas

Valideringsfel

Valideringsfel kommer i de här formerna, beroende på rutten:

• 422 med VALIDATION_FAILED, och en post per fält i details:

  jsonKopiera kod

  {
    "error": "Validation failed.",
    "code": "VALIDATION_FAILED",
    "details": [{ "field": "Name", "message": "…" }]
  }

  Vissa kontroller svarar VALIDATION_FAILED med orsaken i error och utan details.

• 400 med BAD_REQUEST och fältfelen i errors: antingen i standardformatet för problem, per fält, eller som en lista med meddelanden:

  jsonKopiera kod

  {
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": { "Region": ["Region is required"] },
    "code": "BAD_REQUEST"
  }

• 400 med BAD_REQUEST och bara ett meddelande i error.

Behörighetsfel

Ett 403 säger oftast inte vilken behörighet som saknades; rollerna som ger en åtgärd listas på varje moduls behörighetssida. Be en ägare av boundaryn om den roll du behöver.

När kroppens code är FORBIDDEN_REQUESTABLE kan behörigheten begäras som just-in-time-åtkomst: details anger åtgärden, omfattningen och rollen att begära. Se Begär åtkomst. Med VAULT_GRANT_FORBIDDEN har en begäran redan skickats åt dig; se VAULT_GRANT_FORBIDDEN.

Samtidiga ändringar

Appar har stöd för optimistisk samtidighet: att läsa en app returnerar en header ETag, och ett PATCH som skickar tillbaka den som If-Match svarar 412 om appen har ändrats sedan dess. Utan If-Match tillämpas ett PATCH som förlorar en kapplöpning mot en annan ändring på nytt på appen som den ser ut nu, upp till fem gånger, så att samtidiga ändringar av olika fält alla går igenom; först när alla fem försöken förlorar svarar det 409. Andra resurser använder inte ETag eller If-Match; en krockande ändring svarar 409.

Fel från gatewayen

Anrop till en moduls rutter passerar först plattformens kärna, som skickar dem vidare till modulen. Kärnan svarar själv på vissa fel, med "module": "kernel":

• 401 med UNAUTHORIZED och "error": "missing bearer token" — när token saknas, men också när den är ogiltig eller har gått ut.
• 503 med MODULE_UNAVAILABLE när modulen inte kör eller inte svarar. Modulen som den inte nådde står i targetModule. Se MODULE_UNAVAILABLE.

En moduls egna 4xx-svar skickas vidare oförändrade. Ett 5xx-svar från en modul ersätts med {"error": "An internal error occurred.", "code": "…", "module": "…", "correlationId": "…"}, så att detaljerna stannar i plattformens loggar. Modulens code och module behålls, oavsett om koden skrivs med versaler eller gemener — INTERNAL_ERROR, PLATFORM_ERROR och compute_plan_policy_unavailable likaså — så länge de har formen av en kod och en modulnyckel; allt annat utelämnas. Den ersättande kroppen är vanlig JSON, också när modulen svarade i problemformatet, och har inget traceId. Kodens dokumentation säger vad felet betyder. En plattform som kör i utvecklingsläge skickar vidare 5xx-svar oförändrade.

I CLI:t

stsh skriver ut felet och avslutas med en kod som skiljer felen åt: