Desarrolladores

Códigos de error

Todos los códigos HTTP y valores de error.code devueltos por la API Pública de Inkspectra v1.

Formato

Envoltura de error

Cada respuesta de error usa el mismo envoltorio JSON con un code estable, un message legible y el requestId para rastreo en soporte.

{
  "error": {
    "code": "validation_error",
    "message": "sourceType is required.",
    "requestId": "req_01jz..."
  }
}

Incluye el requestId al reportar un problema. También aparece en el header de respuesta X-Request-Id.

HTTP

Códigos de estado

Códigos de estado utilizados por la API y cuándo los encontrarás.

202

Accepted

Analysis queued and will be processed asynchronously.

400

Bad Request

Validation error: missing required field, invalid value, or test/live mode mismatch.

401

Unauthorized

No API key provided, or the key is invalid/expired/revoked.

403

Forbidden

Key is valid but lacks the required scope for this endpoint.

404

Not Found

Resource not found, or not visible for the current organization/mode.

409

Conflict

Operation cannot proceed due to current resource state (e.g. analysis not yet completed).

410

Gone

Endpoint has been retired. The error body contains a replacement pointer.

413

Payload Too Large

Uploaded file exceeds the maximum allowed size.

415

Unsupported Media Type

File type is not accepted (only PDF) or magic bytes do not match the declared MIME type.

422

Unprocessable Entity

PDF could not be parsed or contained no extractable text.

429

Too Many Requests

Rate limit exceeded. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.

503

Service Unavailable

Live execution requested but the runtime cannot process live requests. Use a test key, or retry later.

Códigos de error

Catálogo de error.code

El campo code en el objeto de error. Úsalo para manejo programático — los mensajes pueden cambiar, los códigos son estables.

invalid_api_key

Invalid, expired, or revoked API key.

401

insufficient_scope

The key does not have the required scope for this endpoint.

403

rate_limit_exceeded

Too many requests. Slow down and check the X-RateLimit-* response headers.

429

validation_error

Request body or query parameter failed validation. See message for details.

400

not_found

Resource not found or not accessible under the current organization and mode.

404

analysis_failed

The analysis pipeline failed. The analysisId is still valid; re-submit or create a new analysis.

409

live_execution_unavailable

A live key was used but the runtime cannot execute live analyses. Use fpk_test_* instead.

503

file_too_large

Uploaded PDF exceeds the maximum allowed file size.

413

unsupported_media_type

Only PDF documents (application/pdf) are accepted. The file magic bytes must match.

415

pdf_unreadable

The PDF could not be parsed or contained no extractable text content.

422

endpoint_retired

This endpoint has been retired. The message field contains the replacement endpoint path.

410

internal_error

Unexpected server error. Retry with exponential backoff; contact support if it persists.

500

Headers de respuesta

Headers de diagnóstico

Headers devueltos en cada respuesta /v1.

X-Request-Id

Refleja el requestId del cuerpo de error. Presente en todas las respuestas.

X-RateLimit-Limit

Máximo de solicitudes permitidas en la ventana actual.

X-RateLimit-Remaining

Solicitudes restantes en la ventana actual.

X-RateLimit-Reset

Timestamp Unix (segundos) cuando se restablece la ventana de rate limit.

¿Necesitas el catálogo completo de endpoints?

La Referencia de API lista los 9 endpoints con esquemas de solicitud y respuesta.

Referencia de API Guía Quickstart