Zerobus Ingestie Foutafhandeling

Foutafhandeling

In deze sectie wordt beschreven hoe fouten worden geretourneerd door de Zerobus Ingest-API en hoe clients deze moeten verwerken.

Antwoordindeling voor fouten

REST (JSON)

Foutberichten worden geretourneerd als JSON met de juiste HTTP-statuscode:

{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}

Veld	Typ	Beschrijving
error_code	touw	Een machineleesbare foutcode die de categorie van fouten aangeeft. Gebruik deze methode om te bepalen hoe de fout programmatisch moet worden afgehandeld.
message	touw	Een door mensen leesbare beschrijving van de fout. Kan aanvullende diagnostische gegevens bevatten voor het oplossen van problemen. Parseert dit veld niet programmatisch. De indeling kan zonder kennisgeving worden gewijzigd.

gPRC

Foutreacties maken gebruik van standaard gRPC-statuscodes, geleverd via antwoordtrailers:

Trailer	Beschrijving
grpc-status	Een numerieke statuscode (bijvoorbeeld 3 voor INVALID_ARGUMENT). Gebruik deze methode om te bepalen hoe de fout programmatisch moet worden afgehandeld.
grpc-message	Een door mensen leesbare beschrijving van de fout. Kan aanvullende diagnostische gegevens bevatten voor het oplossen van problemen. Parseert dit veld niet programmatisch. De indeling kan zonder kennisgeving worden gewijzigd.

Foutcodes

De volgende tabel bevat alle foutcodes die worden geretourneerd door de Zerobus Ingest-API, de bijbehorende codes op protocolniveau en het aanbevolen clientgedrag.

Clientfouten

Deze fouten duiden op een probleem met de aanvraag. Probeer het niet opnieuw zonder de aanvraag te wijzigen.

Foutcode (REST)	gRPC-code	HTTP-status	Beschrijving	Aanbevolen actie
INVALID_PARAMETER_VALUE	INVALID_ARGUMENT(3)	400	De aanvraag bevat ongeldige of ongeldige invoer, zoals een ontbrekend vereist veld, een ongeldig schema of een niet-ondersteunde recordindeling.	Corrigeer de aanvraag en dien het opnieuw in. Inspecteer het message veld voor details over welke parameter ongeldig is.
NOT_FOUND	NOT_FOUND(5)	404	De aangevraagde resource bestaat niet. De opgegeven tabel kan bijvoorbeeld niet worden gevonden.	Controleer of de resourcenaam juist is en of deze bestaat.
NOT_IMPLEMENTED	UNIMPLEMENTED(12)	501	De aangevraagde bewerking wordt niet ondersteund. De tabel maakt bijvoorbeeld gebruik van een niet-ondersteunde functie of gegevensindeling.	Probeer het niet opnieuw. Controleer het message veld voor meer informatie over wat niet wordt ondersteund.

Verificatie- en autorisatiefouten

Deze fouten geven problemen aan met de identiteit of machtigingen van de beller. Probeer het niet opnieuw met dezelfde referenties.

Foutcode (REST)	gRPC-code	HTTP-status	Beschrijving	Aanbevolen actie
UNAUTHENTICATED	UNAUTHENTICATED(16)	401	De aanvraag heeft geen geldige verificatiereferenties. Het token ontbreekt mogelijk, leeg, verlopen of is ongeldig.	Vernieuw of geef een geldig verificatietoken op en probeer het opnieuw.
PERMISSION_DENIED	PERMISSION_DENIED(7)	403	De aanroeper heeft onvoldoende bevoegdheden om de aangevraagde bewerking uit te voeren op de opgegeven resource.	Controleer of de aanroeper de vereiste bevoegdheden heeft (bijvoorbeeld MODIFY, SELECT, USE_CATALOG) USE_SCHEMAop de doelresource.

Serverfouten

Deze fouten duiden op een probleem aan de serverzijde. Probeer opnieuw met exponentiële backoff en jitter.

Foutcode (REST)	gRPC-code	HTTP-status	Beschrijving
UNAVAILABLE	UNAVAILABLE(14)	503	De service kan de aanvraag tijdelijk niet verwerken. Dit is meestal een tijdelijke voorwaarde. Probeer opnieuw met exponentiële terugval en jitter.
RESOURCE_EXHAUSTED	RESOURCE_EXHAUSTED(8)	429	De service weigert aanvragen vanwege resourcelimieten. Verminder indien mogelijk gelijktijdigheid van aanvragen. Probeer het opnieuw met exponentiële terugval en jitter.
INTERNAL_ERROR	INTERNAL_ERROR(13)	500	Er is een onverwachte interne fout opgetreden. Probeer het niet opnieuw. Neem contact op met de ondersteuning en geef het volledige foutbericht op voor diagnose.