10. Errores

Todos los errores usan la misma forma:

{
  "error": {
    "code": "PropertyNotFound",
    "message": "'nombre' is not a property of 'o_customers'",
    "details": [ { "code": "", "message": "..." } ]
  }
}

details aparece solo cuando hay más de un mensaje —típicamente validaciones de negocio— y su code siempre viene vacío. No hay target ni innererror. El message está en inglés salvo los mensajes de reglas del ERP, que vienen como los configuró el administrador.

Códigos de estado

Status	Cuándo	Qué hacer
401	Falta el header X-API-Key o Authorization.	Mandar la credencial. No viene WWW-Authenticate.
403	Credencial inválida o inactiva, token vencido, o IP no autorizada.	Ver el code: InvalidApiKey, TokenExpired, IpNotAllowed, UnknownClient.
404	El entity set no existe o no está habilitado para tu cliente; o la entidad con esa clave no existe.	Confirmar el nombre contra el documento de servicio.
405	La operación no está permitida para esa entidad.	Leer el header Allow, que lista los métodos válidos.
406	Se pidió un formato que no se produce.	Usar application/json (o */*). Ver la nota de abajo.
400	Error en la consulta: sintaxis de $filter, propiedad inexistente, clave mal formada, valor inválido.	El message indica la posición o el nombre del problema.
501	Prestación del protocolo no implementada.	Ver No implementado.
500	Error interno.	Reportarlo con la URL y la hora: el detalle queda en el log del servidor.

peligro

Cuidado con el header Accept. La negociación es estricta: solo se aceptan */*, application/*, application/json, application/xml y text/xml. Cualquier otro valor da 406 — incluido Accept: text/plain, incluso pidiendo /$count, cuya respuesta justamente es text/plain. Si tu cliente HTTP pone un Accept por defecto raro, lo más seguro es mandar Accept: application/json o no mandar nada.

Dos aclaraciones más sobre errores:

• Una propiedad inexistente en la ruta devuelve 400 PropertyNotFound, no 404: la entidad existe, lo que está mal es la consulta.
• El header Preference-Applied nunca aparece en una respuesta de error.