Errores de API

La API comunica los errores con códigos de estado HTTP estándar y un cuerpo de respuesta unificado. Las respuestas exitosas devuelven los datos directamente, sin envoltorio.

Formato del error

En caso de error, el cuerpo de la respuesta es un objeto JSON con un campo error que contiene un mensaje legible:

{"error":"reaction not found"}

Oriéntate principalmente por el código de estado HTTP, y usa el texto de error para los logs y los mensajes al usuario.

Códigos de estado

  • 200 OK — solicitud exitosa, los datos están en el cuerpo.
  • 201 Created — nuevo recurso creado (algunos endpoints POST).
  • 204 No Content — éxito sin cuerpo (algunos eliminados).
  • 400 Bad Request — cuerpo o parámetros de solicitud incorrectos.
  • 401 Unauthorized — el token está ausente, es incorrecto o ha expirado; o la ruta no está disponible con un token personal.
  • 402 Payment Required — la acción choca con el plan o la cuota (por ejemplo, el almacenamiento propio de medios requiere premium).
  • 403 Forbidden — al token le falta el área de acceso necesaria para esta ruta.
  • 404 Not Found — el recurso no existe o no te pertenece.
  • 409 Conflict — conflicto de estado (por ejemplo, duplicado de un valor único).
  • 422 Unprocessable Entity — el cuerpo es sintácticamente válido pero no pasa las validaciones de dominio.
  • 429 Too Many Requests — se superó el límite de solicitudes (ver límites).
  • 500 Internal Server Error — error interno del servidor; inténtalo de nuevo más tarde.

Cómo manejarlos

Considera exitosos los códigos 2xx. Ante 401/403 verifica el token y sus áreas de acceso. Ante 4xx (salvo 429) no repitas la solicitud sin cambios — corrige la solicitud. Ante 429 y 5xx es apropiado reintentar con retroceso exponencial.

Qué sigue