Errores

Obtener una clave de API

Cada error responde con un estado HTTP y el mismo envoltorio JSON. code es el contrato que lee tu código; message está escrito para una persona y puede cambiar.

json
{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}
  • details dice más: el campo rechazado, el motivo de una red, la ventana de límite agotada.
  • docUrl lleva a la explicación del código en esta página.
  • requestId identifica la petición: facilítalo al soporte.

Códigos de error

EstadoCódigoSignificado
400invalid_requestEl cuerpo, la consulta o un parámetro no es válido. Un detalle por campo rechazado: field, code (required, is_string, max…) y message.
400invalid_jsonEl cuerpo no es JSON válido.
400invalid_cursorEl cursor no lo devolvió Sofia API.
400webhook_url_invalidLa dirección del webhook no es https, o lleva a una dirección privada.
400webhook_event_invalidEvento de webhook desconocido.
400application_name_invalidAjustes › API: falta el nombre del cliente o es demasiado largo.
400application_profile_invalidAjustes › API: un campo del perfil del cliente no es válido; el detalle lo indica.
400logo_invalidAjustes › API: el logotipo se rechaza (mínimo 180×180 px, PNG, JPEG o WebP, 2 MB como máximo).
401invalid_tokenEl token falta, es desconocido, ha caducado o está revocado, o la persona que hay detrás perdió los derechos que lleva. Consulta la cabecera WWW-Authenticate.
401unauthorizedSe requiere autenticación.
402subscription_requiredUna escritura real (simulación incluida) exige una suscripción activa o una prueba.
403insufficient_scopeAl token le falta el scope del endpoint; el detalle lo nombra.
403insufficient_roleTu rol en este Workspace no permite esta acción.
403live_mode_requiredUna escritura real con un token de prueba.
403route_closed_to_applicationsEste endpoint no está abierto a aplicaciones.
403forbiddenAcceso denegado.
403session_requiredAjustes › API: esta acción requiere una sesión de Sofia, no un token.
403impersonation_forbiddenAjustes › API: esta acción se rechaza en una sesión prestada.
403workspace_owner_requiredSolo el propietario del Workspace puede hacerlo.
403workspace_member_requiredNo eres miembro de este Workspace.
404route_not_foundNingún endpoint responde a este método y esta ruta.
404establishment_not_foundEstablecimiento desconocido, o fuera del alcance del token.
404media_not_foundMedio desconocido, o fuera del alcance del token.
404post_not_foundPublicación desconocida, o fuera del alcance del token.
404webhook_not_foundWebhook desconocido, o de otra aplicación.
404not_foundEl recurso no existe.
404application_not_foundAjustes › API: cliente desconocido.
404grant_not_foundAutorización desconocida o ya revocada.
404personal_key_not_foundAjustes › API: clave personal desconocida.
405method_not_allowedEste método no está permitido en este endpoint.
409post_in_flightUna red está enviando la publicación: reintenta la eliminación un momento después.
409post_not_editableUna red ya envió la publicación: ya no se puede editar.
409account_already_connectedEsta red ya está conectada al establecimiento.
409webhook_limit_reachedLa aplicación ya tiene 10 webhooks.
409idempotency_in_progressLa primera petición con esta Idempotency-Key sigue en curso.
409conflictLa solicitud entra en conflicto con el estado actual del recurso.
409scope_removal_forbiddenAjustes › API: a un cliente se le puede añadir un permiso, pero no quitárselo.
409public_client_has_no_secretAjustes › API: un cliente público no tiene secreto.
413payload_too_largeEl archivo supera el límite de subida.
415unsupported_media_typeTipo de contenido no admitido.
422post_refusedUna red, el establecimiento o tu plan rechazaría la publicación. Un detalle por motivo, cada uno con su message.
422media_import_refusedNo se pudo importar el medio desde esta URL; el detalle da el motivo.
422media_upload_refusedEl archivo subido no es una imagen o un vídeo admitido.
422platform_not_offeredEsta red no se ofrece para conectar.
422idempotency_key_reusedEsta Idempotency-Key se usó con un cuerpo distinto.
422unprocessable_entityLa solicitud se entiende, pero no se puede procesar.
429rate_limit_exceededUna ventana de límite está llena: espera el tiempo de Retry-After.

Motivos de una publicación rechazada

Un post_refused enumera cada motivo en details[].code:

CódigoSignificado
unsupported_platformEsta red no es compatible.
duplicate_platformLa misma red aparece dos veces.
unsupported_formatEsta red no ofrece este formato.
caption_too_longEl texto es demasiado largo (max, actual).
too_many_hashtagsDemasiados hashtags (max, actual).
too_many_mentionsDemasiadas menciones (max, actual).
too_many_thread_postsEl hilo es demasiado largo (max, actual).
too_many_mediaDemasiados medios (max, actual).
media_mix_refusedNo se pueden mezclar fotos y vídeos en esta red.
media_requiredEsta red necesita una foto o un vídeo.
media_type_refusedEsta red no acepta este tipo de medio.
scheduled_in_pastscheduledAt está en el pasado.
scheduled_at_invalidUna publicación programada necesita un scheduledAt futuro.
account_not_connectedNo hay ninguna cuenta conectada en esta red para este establecimiento.
account_ambiguousHay varias cuentas conectadas en esta red: indica una con accountId.
media_not_foundEl medio no está en la biblioteca de este establecimiento.
media_url_invalidLa URL del medio debe ser una dirección https pública.
platform_unavailableEsta red todavía no está abierta en Sofia.
publication_quota_exceededSe alcanzó la cuota de publicaciones de tu plan.

Gestionar los errores

  • Bifurca según code, nunca según message.
  • Reintenta un 429 tras Retry-After, y un 5xx con un backoff exponencial.
  • Nunca reintentes un 4xx sin cambios: corrige primero la petición.
  • Registra requestId en cada fallo.