v1 · vista previa

Prueba con webhook firma, alert.created, location_withheld o 429.

↑ ↓ moverseIntro abrirEsc cerrar
SafeOnuba
Pedir acceso a la APIVolver a la web

Funcionamiento

Errores

Los errores llegan en application/problem+json (RFC 9457) con el código HTTP real y un code estable para programar contra él.

En esta página

Los errores llegan con el código HTTP real y un cuerpo en application/problem+json, el formato de la RFC 9457. La excepción es el endpoint del token, que sigue el formato de OAuth2 (ver Errores del token).

El cuerpo

CampoQué es
typeURI que identifica el tipo de problema.
titleResumen legible.
statusEl código HTTP, repetido.
detailExplicación de este caso concreto.
instanceLa ruta que ha fallado.
codeCódigo estable del error, para programar contra él. El texto de title y detail puede cambiar; code no.
403 · application/problem+json
{
  "type": "https://api.safeonuba.com/problems/insufficient-scope",
  "title": "Falta un permiso del token",
  "status": 403,
  "detail": "Esta petición necesita el scope alerts:write.",
  "instance": "/v1/alerts/0f6c2b7e-3a1d-4c55-9b0e-7d2f4a8c1e90",
  "code": "insufficient_scope"
}

Programa contra status y code, nunca contra el texto.

Códigos

CódigoCuándoQué hacer
401Falta el token, ha caducado o se ha revocado.Pide un token nuevo y reintenta una vez.
403Al token le falta el scope que pide la ruta, o el centro no es de tu cliente.Pide el token con ese scope; si tu cliente no lo tiene, pídelo. No reintentes.
404No existe, o tu identidad no lo ve (otro centro, otra contrata).No reintentes.
409La transición no es posible: por ejemplo, reconocer o cerrar una alerta ya cerrada. En el sandbox, también demasiados escenarios abiertos.Vuelve a leer el recurso: probablemente ya está en el estado que querías.
422La petición no cumple el contrato: un campo que falta, un valor fuera de rango, una URL de webhook que no es https.Corrige la petición. detail dice qué falla.
429Has superado un límite de uso.Espera lo que diga Retry-After (ver Límites de uso).

Reintentar o no

  • 401: sí, una vez, con un token nuevo.
  • 429: sí, después de Retry-After.
  • Errores de red y 5xx: sí, con espera creciente. Las lecturas se pueden repetir sin problema. Antes de repetir un PUT /v1/alerts/{id}, vuelve a leer la alerta: puede que el primero sí llegara.
  • 403, 404, 409 y 422: no. Repetir la misma petición dará el mismo resultado.