Códigos de error de Request
Todos los códigos de error de la API pública que emite Request, con su estado HTTP, su type y una página por código.
Códigos de error que emite Request. Cada code enlaza a su propia página con la causa y la acción a tomar.
| Code | Type | HTTP | Descripción |
|---|---|---|---|
business_rule_violation | invalid_request_error | 422 | Una invariante del dominio rechazó la operación. Este código indica la familia; error.subcode nombra la regla concreta y error.message la explica. |
conflicting_pagination_params | invalid_request_error | 422 | starting_after y ending_before viajaron en la misma petición. Recorren la colección en sentidos opuestos, así que solo puede aplicarse uno. |
external_id_already_exists | conflict_error | 409 | El external_id con el que concilias contra tu sistema ya está asignado a otro objeto del mismo tipo en esta empresa. |
invalid_param_format | invalid_request_error | 422 | Un form request legacy rechazó la forma de un valor. Los endpoints migrados reportan lo mismo como parameter_invalid_format o parameter_invalid_integer. |
invalid_param_value | invalid_request_error | 422 | Un form request legacy rechazó el valor de un campo. Los endpoints migrados reportan lo mismo como parameter_invalid_enum o parameter_invalid_range. |
invalid_status_transition | invalid_request_error | 422 | El estado solicitado no es alcanzable desde el estado en el que está ahora mismo el documento. |
length_required | invalid_request_error | 411 | Llegó una petición con body en codificación chunked, sin declarar su tamaño. La API necesita conocer la longitud por adelantado para rechazar payloads excesivos antes de cargarlos en memoria. |
metadata_too_many_keys | invalid_request_error | 422 | El objeto metadata supera el límite de 50 claves por recurso. |
metadata_value_too_long | invalid_request_error | 422 | Un valor de metadata supera los 500 caracteres una vez serializado a texto. |
method_not_allowed | invalid_request_error | 405 | La ruta existe pero no acepta el verbo HTTP utilizado. |
missing_required_param | invalid_request_error | 422 | Un form request legacy detectó que faltaba un campo obligatorio. Los endpoints ya migrados a los parsers canónicos reportan lo mismo como parameter_missing. También lo devuelve una línea de factura, presupuesto, proforma, albarán o factura recurrente sin tax_rate cuando ni el producto tiene impuesto asignado ni tu empresa tiene un IVA por defecto para ese tipo de documento: error.param es lines.N.tax_rate y error.line_index es la posición (base 0) de esa línea. También lo devuelve POST /v1/companies/{company}/invoices cuando pides el envío por correo (options.send_automatically) y no hay destinatario posible —sin cliente, o con un cliente sin email, y sin options.send_to—: error.param es options.send_to y no se crea ninguna factura. |
parameter_invalid | invalid_request_error | 422 | Un value object construido a partir del payload rechazó el valor recibido. error.subcode dice cuál: código de impuesto, código de país, tipo impositivo, etc. |
parameter_invalid_boolean | invalid_request_error | 400 | Un parámetro que debe ser booleano recibió un valor fuera de las representaciones aceptadas (true/false, 1/0). |
parameter_invalid_cursor | invalid_request_error | 400 | El cursor starting_after o ending_before no es un UUID válido, así que no puede apuntar a ninguna fila de la colección. |
parameter_invalid_empty | invalid_request_error | 400 | Un parámetro llegó con el valor vacío: un filtro in sin elementos, una comparación sin nada tras el operador, o un filtro de igualdad con la cadena vacía. |
parameter_invalid_enum | invalid_request_error | 400 | El valor queda fuera del conjunto cerrado que acepta el parámetro. En los listados cubre además un operador de filtro distinto de eq, gte, lte, gt, lt, in o contains, y sale como código principal (400). En las operaciones que validan un formulario o un parámetro de consulta con reglas (por ejemplo format en los PDF de factura) llega como entrada de error.errors[], con su allowed_values, dentro de un 422 invalid_param_value. |
parameter_invalid_format | invalid_request_error | 400 | El valor tiene el tipo correcto pero no la forma que exige el parámetro: una fecha, un patrón de identificador o una cabecera como Factuarea-Version. |
parameter_invalid_integer | invalid_request_error | 400 | Un parámetro que debe ser un número entero recibió algo que no se puede interpretar como tal, por ejemplo limit=abc. |
parameter_invalid_iso8601 | invalid_request_error | 400 | Un filtro de rango (gte, lte, gt, lt) recibió un valor que no es numérico ni una fecha ISO 8601. |
parameter_invalid_range | invalid_request_error | 400 | Un parámetro numérico quedó fuera de sus límites. El caso habitual es limit, que debe estar entre 1 y 100. |
parameter_invalid_string | invalid_request_error | 400 | Un parámetro que debe ser texto recibió un array, un objeto o un valor que no se puede leer como cadena. |
parameter_invalid_url | invalid_request_error | 400 | Un campo que debe contener una URL absoluta recibió un valor que no lo es, normalmente por faltarle el esquema o el host. |
parameter_invalid_uuid | invalid_request_error | 400 | Un campo de identificador recibió un valor que no es un UUID válido. Todo id de recurso en v1 es un UUID. |
parameter_invalid_value | invalid_request_error | 422 | El valor es sintácticamente correcto pero no admisible para este recurso: fuera del catálogo canónico del campo, o incoherente con el resto del payload. |
parameter_missing | invalid_request_error | 400 | El endpoint exige un parámetro que la petición no llevaba. error.param dice cuál. |
parameter_unknown | invalid_request_error | 400 | La petición lleva un parámetro que el endpoint no acepta: un filtro fuera de su allowlist, un campo de sort no ordenable, el page de paginación por offset —v1 pagina por cursor— o una cabecera retirada de la v1. |
payload_too_large | invalid_request_error | 413 | El body de la petición supera el tamaño admitido: 1 MB con carácter general, 6 MB en los endpoints que aceptan ficheros. |
profile_not_found | not_found_error | 404 | El segmento {company} de la ruta nombra una empresa que no existe o que no está en el ámbito de NIFs de la credencial. Ambos casos responden igual para que la API nunca revele empresas de otras cuentas. |
resource_already_exists | conflict_error | 409 | Crear el objeto duplicaría uno que ya existe bajo una clave única — NIF, SKU, external id. error.details.existing_resource_id apunta al objeto que ya ocupa ese valor. |
resource_conflict | conflict_error | 409 | La operación chocó con el estado actual del recurso y no aplica ningún código de conflicto más específico. |
resource_immutable | invalid_request_error | 422 | El objeto está cerrado a cambios para esta operación: su estado o su registro contable impiden modificarlo. |
resource_locked | conflict_error | 409 | Otra operación retiene el recurso hasta terminar: las escrituras concurrentes sobre el mismo objeto se serializan en lugar de entrelazarse. En POST /v1/companies/{company}/invoices con external_id, otra petición con el MISMO external_id sigue en curso y no terminó tras esperarla 20 segundos. |
resource_not_deletable | invalid_request_error | 422 | El objeto existe, pero su estado o sus dependientes bloquean el borrado. En los borrados masivos este es el código por fila de cada entrada que no se pudo eliminar. |
resource_not_found | not_found_error | 404 | El identificador no resuelve a nada visible para la empresa autenticada. Los objetos de otra empresa responden exactamente igual, a propósito. |
route_not_found | not_found_error | 404 | La ruta no corresponde a ningún endpoint de v1. Suele ser una errata, un prefijo /v1 ausente, una ruta de otra área de la API o la forma plana de una ruta que la ventana de ruptura trasladó al segmento de empresa o de cuenta; en ese último caso error.subcode vale legacy_route_moved. |
unknown_filter | invalid_request_error | 422 | Un listado recibió un filtro que no conoce. Los parsers canónicos de v1 reportan esto como parameter_unknown; este código sobrevive para los endpoints aún sin migrar. |
unsupported_api_version | invalid_request_error | 400 | La cabecera Factuarea-Version está bien formada pero nombra una versión fuera del conjunto soportado. |
unsupported_media_type | invalid_request_error | 415 | Una petición con body declaró un Content-Type distinto de application/json. |
Relacionado
Códigos de error por categoría
Localiza un error por la categoría que lo emite.
Tabla de referencia completa
Todos los códigos, estados HTTP, tipos y descripciones en una referencia.
Modelo de errores
Interpreta la respuesta de error y gestiona los errores por código.