Límites y errores
Tu plan
Cada documento que Ocost lee cuenta una vez en el mes de tu empresa. Los bytes reenviados y las búsquedas no cuentan nada. Ajustes › Plan y facturación muestra el mes hasta ahora. Cada respuesta de POST /public/v1/files dice lo que queda en X-Ocost-Documents-Left.
En el límite, Ocost sigue guardando el archivo. Responde not_read con reason: "limit" y renews_on. Ocost lee el archivo por sí solo cuando el mes se renueva o el plan crece.
Límites de frecuencia
Cada clave tiene un límite por minuto para cada permiso:
| Permiso | Llamadas por minuto |
|---|---|
documents:write | 120 |
documents:read | 600 |
search:read | 60 |
figures:read | 120 |
exports:write | 10 |
Por encima de un límite, Ocost responde 429 urn:ocost:key:rate con Retry-After en segundos. Desde una dirección, 30 claves erróneas por minuto reciben 401, y las siguientes 429.
Todas las claves desde una dirección comparten un límite exterior: 50 solicitudes por segundo, ráfagas de hasta 200 y 100 abiertas a la vez. Por encima, vuelve un 429 en texto plano con Retry-After. Mantén pocas solicitudes a la vez y reparte un lote a lo largo de su minuto.
Tamaños
| Qué | Límite |
|---|---|
| Un archivo | 25 MB, rechazado antes de leerlo con 413 urn:ocost:file:too_large |
| Un PDF largo | Solo se leen sus primeras páginas. pages_read dice cuántas. |
| Una búsqueda | q hasta 200 caracteres, limit hasta 50, offset hasta 250 |
| Una solicitud MCP | 4 MB. Las claves con documents:write pueden enviar el base64 de un archivo. Por encima, 413. |
Errores
Los errores son problemas RFC 9457 con Content-Type: application/problem+json. Decide según status y type. detail está en inglés para tus logs y puede cambiar.
{
"type": "urn:ocost:key:scope",
"title": "Forbidden",
"status": 403,
"detail": "This key lacks the scope documents:write.",
"instance": "/public/v1/files"
}| Tipo | Estado | Significado |
|---|---|---|
urn:ocost:key:invalid | 401 | Ninguna clave, o una errónea, revocada o caducada. |
urn:ocost:key:scope | 403 | A la clave le falta el permiso. |
urn:ocost:key:rate | 429 | Demasiadas llamadas. Espera Retry-After. |
urn:ocost:file:too_large | 413 | El archivo supera los 25 MB. |
urn:ocost:file:format | 415 | Un formato que Ocost no lee. |
urn:ocost:file:reading | 409 | El archivo se está leyendo. Bórralo más tarde. |
urn:ocost:file:kept | 409 | Los mismos bytes se guardan donde las claves no los ven, como la subida propia de una persona. Nada cambia. |
urn:ocost:file:linked | 409 | Ocost aún necesita el archivo. Bórralo en Ocost cuando nada lo necesite. |
about:blank | 404 | No existe ese archivo o documento, o es de otra empresa. |
about:blank | 422 | Campos no válidos, cada uno en errors[] con su loc. |
about:blank | 503 | Vuelve a intentarlo en breve. |
Un archivo enviado sin cabecera Content-Length recibe 411.
Reintentar
| Respuesta | Qué hacer |
|---|---|
429, 5xx | Espera Retry-After, o haz una pausa de 1, 2, 4 segundos y así sucesivamente, como máximo un minuto. |
401 | Para y avisa a una persona. Hay que sustituir la clave. |
Cualquier otro 4xx | No envíes la misma solicitud otra vez. |
Reenviar un archivo es seguro, porque los mismos bytes son el mismo archivo. Borrar otra vez también es seguro, y responde 404.
Tus datos
Ocost funciona en la UE. Los originales, las lecturas y el índice de búsqueda se quedan hasta que borras el archivo o se borra tu empresa. Los documentos nunca entrenan un modelo.