Códigos de error

La API usa el formato RFC 7807 Problem Details para todos los errores. Este estándar proporciona una estructura consistente y legible para comunicar problemas.

Formato de error

{
  "type": "https://api.evaluax.es/errores/recurso-no-encontrado",
  "title": "Recurso no encontrado",
  "status": 404,
  "detail": "Declaracion con ID 999 no encontrada.",
  "instance": "/apientidades/v1/declaraciones/999",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Campos del error

Campo	Tipo	Descripción
type	string	URI que identifica el tipo de error (único por tipo)
title	string	Título corto y genérico del error
status	int	Código HTTP del error
detail	string	Explicación detallada específica de esta petición
instance	string	Ruta de la petición que falló
traceId	string	ID de correlación para soporte (coincide con cabecera X-Correlation-ID)

Códigos HTTP utilizados

Código	Significado	Cuándo ocurre
200	OK	Petición exitosa (lectura o actualización)
201	Created	Recurso creado (incidencias, webhooks)
400	Bad Request	Parámetros inválidos, body malformado, validación fallida
401	Unauthorized	Token ausente, expirado o API Key inválida
404	Not Found	Recurso no existe o no pertenece a la entidad
500	Internal Server Error	Error inesperado del servidor

Tipos de error

400 Bad Request

Se produce cuando los datos enviados no son válidos:

Validación de campoEstado no permite operaciónBulk con errores

{
  "type": "https://api.evaluax.es/errores/validacion",
  "title": "Error de validación",
  "status": 400,
  "detail": "opcionPublicacion debe ser 0-3",
  "instance": "/apientidades/v1/declaraciones/5001/pa/7001"
}

{
  "type": "https://api.evaluax.es/errores/estado-no-permite-operacion",
  "title": "Operación no permitida",
  "status": 400,
  "detail": "La declaración está en estado 'PendienteRevision' y no permite modificaciones.",
  "instance": "/apientidades/v1/declaraciones/5001/pa/7001"
}

{
  "type": "https://api.evaluax.es/errores/validacion-bulk",
  "title": "Errores de validación",
  "status": 400,
  "detail": "3 ítems con errores de validación (mostrando primeros 10)",
  "instance": "/apientidades/v1/declaraciones/5001/pa",
  "errors": [
    "Ítem 0 (obligacionId 7001): URL demasiado larga (max 2048 caracteres)",
    "Ítem 2 (obligacionId 7003): opcionPublicacion debe ser 0-3",
    "Ítem 5 (obligacionId 7004): Máximo 10 enlaces por obligación"
  ]
}

401 Unauthorized

Se produce cuando hay problemas de autenticación:

Token expiradoAPI Key inválida

{
  "type": "https://api.evaluax.es/errores/token-expirado",
  "title": "Token expirado",
  "status": 401,
  "detail": "El token JWT ha expirado. Obtenga uno nuevo con POST /auth.",
  "instance": "/apientidades/v1/evaluaciones"
}

{
  "type": "https://api.evaluax.es/errores/autenticacion",
  "title": "Autenticación fallida",
  "status": 401,
  "detail": "API Key inválida o entidad desactivada.",
  "instance": "/apientidades/v1/auth"
}

404 Not Found

Se produce cuando el recurso no existe o no pertenece a la entidad:

{
  "type": "https://api.evaluax.es/errores/recurso-no-encontrado",
  "title": "Recurso no encontrado",
  "status": 404,
  "detail": "Declaracion con ID 999 no encontrada.",
  "instance": "/apientidades/v1/declaraciones/999"
}

404 por seguridad

Cuando una entidad intenta acceder a un recurso de otra entidad, la API devuelve 404 en lugar de 403. Esto evita revelar la existencia de recursos de otras entidades.

500 Internal Server Error

Error inesperado del servidor:

{
  "type": "https://api.evaluax.es/errores/interno",
  "title": "Error interno",
  "status": 500,
  "detail": "Error inesperado al procesar la petición.",
  "instance": "/apientidades/v1/declaraciones/5001/inicializar",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Manejo recomendado de errores

PythonC#

response = requests.put(f"{BASE_URL}/declaraciones/5001/pa/7001",
                       headers=headers, json=payload)

if response.status_code == 200:
    print("OK:", response.json())
elif response.status_code == 400:
    error = response.json()
    print(f"Validación: {error.get('detail')}")
    if "errors" in error:
        for e in error["errors"]:
            print(f"  - {e}")
elif response.status_code == 401:
    print("Token expirado, renovando...")
    # Renovar token y reintentar
elif response.status_code == 404:
    print("Recurso no encontrado")
else:
    error = response.json()
    print(f"Error {response.status_code}: {error.get('detail')}")
    print(f"TraceId: {error.get('traceId')}")

var response = await client.PutAsync(url, content);

switch (response.StatusCode)
{
    case HttpStatusCode.OK:
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"OK: {result}");
        break;
    case HttpStatusCode.BadRequest:
        var error = JsonConvert.DeserializeObject<ProblemDetails>(
            await response.Content.ReadAsStringAsync());
        Console.WriteLine($"Validación: {error.Detail}");
        break;
    case HttpStatusCode.Unauthorized:
        // Renovar token y reintentar
        break;
    case HttpStatusCode.NotFound:
        Console.WriteLine("Recurso no encontrado");
        break;
    default:
        var serverError = await response.Content.ReadAsStringAsync();
        Console.WriteLine($"Error: {serverError}");
        break;
}

TraceId para soporte

Si recibe un error 500, incluya el traceId (o la cabecera X-Correlation-ID) al contactar con el equipo de soporte. Esto permite localizar el error exacto en los logs del servidor.