Errores

Última actualización July 28, 2026

Cada error comparte un mismo envoltorio JSON, de modo que puedes gestionarlos de forma uniforme:

JSON

{
  "error": {
    "type": "invalid_request",
    "message": "Query parameter 'q' is required.",
    "request_id": "a1b2c3d4e5f6a7b8"
  }
}

type — un código estable y legible por máquina (decide según esto, no según message).
message — una explicación legible por humanos.
request_id — el mismo valor que la cabecera de respuesta X-Request-Id; cítalo a soporte.

Tipos de error

Estado	`type`	Cuándo ocurre
400	`invalid_request`	Falta un parámetro requerido o está mal formado (p. ej. un `q` vacío).
401	`unauthorized`	No hay clave de API, o la clave es inválida / revocada.
403	`insufficient_scope`	La clave existe pero carece del ámbito `search` que el endpoint requiere.
402	`payment_required`	No hay una membresía de Suede activa.
402	`insufficient_credits`	Tu saldo de crédito de API está vacío. Compra crédito o activa la recarga automática.
429	`rate_limited`	Has superado el límite de frecuencia. Consulta Límites de frecuencia.

Cabeceras relacionadas con la facturación

Un endpoint facturado con crédito también devuelve tu saldo en cada respuesta, incluidas las respuestas de error de arriba:

Cabecera	Significado
`X-Credits-Balance`	Saldo de crédito restante, en unidades menores de la moneda (p. ej. céntimos).
`X-Credits-Requests-Remaining`	Número aproximado de peticiones adicionales que cubre ese saldo.
`X-Credits-Currency`	Código ISO en minúsculas en el que está denominado el saldo (las unidades menores siguen esta moneda; las divisas sin decimales no van ×100).

Lectura de los errores

cURL

curl -s "https://api.suede.io/v1/search" \
  -H "Authorization: Bearer $SUEDE_API_KEY"
# => HTTP 400  {"error":{"type":"invalid_request","message":"Query parameter 'q' is required.","request_id":"…"}}

using System.Text.Json;
var res = await http.GetAsync("https://api.suede.io/v1/search"); // missing q
if (!res.IsSuccessStatusCode)
{
    using var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    var err = doc.RootElement.GetProperty("error");
    Console.WriteLine($"{(int)res.StatusCode} {err.GetProperty("type").GetString()}: {err.GetProperty("message").GetString()}");
}

JavaScript

const res = await fetch("https://api.suede.io/v1/search", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  console.error(`${res.status} ${error.type}: ${error.message} (request ${error.request_id})`);
}