Códigos de Error

La API usa códigos HTTP estándar para indicar el resultado de cada request.

Códigos HTTP

Codigo	Significado	Descripcion
200	OK	Request exitoso
201	Created	Recurso creado (API key)
400	Bad Request	Parametros inválidos o formato incorrecto
401	Unauthorized	API key faltante o inválido
403	Forbidden	Sin permisos para acceder al recurso
404	Not Found	Recurso no encontrado
422	Unprocessable Entity	Datos de validación incorrectos
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Error interno del servidor

Formato de errores

Todos los errores retornan un JSON con el campo detail:

{
  "detail": "Template not found"
}

Para errores de validación (422), el detalle puede ser un array:

{
  "detail": [
    "Este achievement requiere calificación (LetterGrade)",
    "Este achievement requiere créditos obtenidos"
  ]
}

Errores comunes

Autenticacion

Error	Causa	Solucion
API key required	No se envió header	Agrega X-API-Key al request
Invalid API key format	Key no empieza con uc_live_	Verifica que copias el key completo
Invalid or revoked API key	Key no existe o fue revocado	Crea un nuevo key en el panel

Templates

Error	Causa	Solucion
Template not found	ID no existe o no es de tu org	Verifica el ID con GET /templates
Invalid template_id format	ID no es un UUID válido	Usa el formato UUID correcto

Emisión

Error	Causa	Solucion
Este achievement requiere calificación	Falta result_value	Consulta campos requeridos en GET /templates/\{id\}
Calificación inválida	Valor no está en allowed_values	Usa uno de los valores permitidos
Los créditos no pueden exceder	credits_earned > credits_available	Ajusta el valor
Este achievement requiere evidencia	Falta array evidence	Incluye al menos un objeto de evidencia

Rate Limiting

Error	Causa	Solucion
Rate limit exceeded	Muchos requests en poco tiempo	Espera el tiempo indicado en Retry-After