Errores

Cuando una solicitud falla, la API devuelve un objeto JSON de error consistente independientemente del endpoint. El código de estado HTTP indica la categoría de la falla; el cuerpo proporciona los detalles.

Estructura del Error

{
  "statusCode": 400,
  "error": "validation_error",
  "message": "Model validation failed.",
  "details": {
    "itemID": ["The itemID field is required."],
    "units": ["The field units must be greater than 0."]
  }
}

El objeto details mapea nombres de campo a arreglos de mensajes de error. Solo está presente cuando el código de error es validation_error.

Códigos de Error

Códigos de Estado HTTP

Errores de Validacion

Cuando envía datos inválidos, la API devuelve un 400 con detalle a nivel de campo:

curl -X POST https://su-host/api/v1/Item \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "statusCode": 400,
  "error": "validation_error",
  "message": "Model validation failed.",
  "details": {
    "itemID": ["The itemID field is required."]
  }
}

Corrija los campos señalados y reintente.

Errores de Permisos

Si sus credenciales no incluyen el permiso requerido:

{
  "statusCode": 403,
  "error": "forbidden",
  "message": "Insufficient permissions."
}

Otras variantes de 403:

Errores de Limite de Tasa

{
  "message": "Rate Limit Exceeded. 100 per Minute"
}

Nota: La respuesta de límite de tasa usa un formato más simple que la estructura estándar de error. Espere y reintente después de un intervalo razonable (30-60 segundos).

Manejo de Errores en Código

var response = await client.PostAsync(url, content);
if (!response.IsSuccessStatusCode)
{
    var body = await response.Content.ReadAsStringAsync();
    var error = JsonConvert.DeserializeObject<ApiError>(body);

    switch (error.Error)
    {
        case "validation_error":
            // Fix the fields listed in error.Details
            break;
        case "rate_limited":
            // Wait and retry
            break;
        case "unauthorized":
            // Token expired — refresh and retry
            break;
        default:
            // Log and alert
            break;
    }
}

$response = Invoke-WebRequest -Uri $url -Method Post -Body $json `
    -Headers @{ Authorization = "Bearer $token" } `
    -ContentType "application/json" -ErrorAction SilentlyContinue

if ($response.StatusCode -ge 400) {
    $error = $response.Content | ConvertFrom-Json
    Write-Warning "$($error.error): $($error.message)"
}