Errores GraphQL
Maneja data, errors, estados HTTP y GraphQLResponseError en Storefront API.
Última actualización:
Una respuesta GraphQL usa un envelope JSON con data y, cuando la ejecución encuentra problemas, errors. Revisa ambos además del estado HTTP.
HTTP 200 no garantiza una ejecución sin errores
Una operación GraphQL puede devolver HTTP 200 e incluir errors. Comprobar únicamente response.ok no es suficiente.
Forma de la respuesta
Una ejecución correcta contiene data:
{
"data": {
"store": {
"id": "7204558912004325301",
"name": "Mi tienda"
}
}
}Cuando un resolver rechaza la operación, la respuesta incluye errors. data puede ser null, como en este argumento inválido:
{
"errors": [
{
"message": "Product ID is invalid.",
"path": ["relatedProducts"],
"extensions": {
"code": "BAD_USER_INPUT"
}
}
],
"data": null
}| Campo | Uso |
|---|---|
data | Resultado de los campos solicitados cuando están disponibles. |
errors | Lista de errores detectados durante la ejecución. |
errors[].message | Mensaje de diagnóstico. No lo uses como identificador estable. |
errors[].path | Ruta del campo que produjo el error, cuando está disponible. |
errors[].extensions.code | Código que permite distinguir casos conocidos, cuando está disponible. |
Los errores de parseo o validación del documento pueden usar otros códigos del runtime GraphQL.
Códigos de los resolvers públicos
Los resolvers públicos de Storefront usan estos valores en extensions.code:
| Código | Significado | Acción inicial |
|---|---|---|
BAD_USER_INPUT | Un argumento, filtro, límite o ID no es válido. | Corrige la entrada; no repitas la misma operación sin cambios. |
NOT_FOUND | El recurso solicitado no existe o no es visible. | Verifica el ID o slug, la tienda resuelta y la visibilidad del recurso. |
STORE_CONTEXT_REQUIRED | No fue posible resolver la tienda desde x-Store-Domain. | Verifica que el header contenga un slug o dominio configurado. |
Toma decisiones con extensions.code, no comparando el texto de message.
Manejo con fetch
Comprueba primero el estado del transporte y luego el envelope GraphQL:
const response = await fetch("https://storefront.ecomiq.pe/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-Store-Domain": "mi-tienda",
},
body: JSON.stringify({
query: "query Store { store { id name } }",
}),
});
const result = await response.json();
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
if (result.errors?.length) {
const firstError = result.errors[0];
const code = firstError.extensions?.code;
switch (code) {
case "BAD_USER_INPUT":
console.error("Corrige los argumentos de la consulta.");
break;
case "NOT_FOUND":
console.error("El recurso no existe o no es visible.");
break;
case "STORE_CONTEXT_REQUIRED":
console.error("Verifica x-Store-Domain.");
break;
default:
console.error(firstError.message);
}
throw new Error(firstError.message);
}
console.log(result.data.store);No accedas a result.data antes de revisar errors.
Manejo con GraphQLResponseError
@ecomiq/storefront valida data con el schema Zod que entregas a graphql(). El método lanza GraphQLResponseError si la respuesta contiene errors o si data no cumple ese schema.
import {
createClient,
GraphQLResponseError,
z,
} from "@ecomiq/storefront";
const SellerData = z.object({
seller: z.object({
id: z.string(),
name: z.string(),
slug: z.string(),
}),
});
const api = createClient();
try {
const data = await api.graphql(
`
query Seller($slug: String!) {
seller(slug: $slug) { id name slug }
}
`,
SellerData,
{ slug: "acme" },
);
console.log(data.seller);
} catch (error) {
if (!(error instanceof GraphQLResponseError)) {
throw error;
}
for (const graphQLError of error.errors) {
console.error(
graphQLError.extensions?.code ?? "GRAPHQL_ERROR",
graphQLError.message,
);
}
}GraphQLResponseError.errors conserva los errores del envelope. GraphQLResponseError.data conserva cualquier data recibido; valida su presencia antes de usarlo.