Referencia de la API
Códigos de error
Todos los códigos de error que puede devolver la API, con su estado HTTP y qué hacer. Envío y recepción usan formatos de error distintos.
Enviar email
Los errores devuelven un objeto JSON con error, code y responseTime. Consulta Enviar email.
- 401
MISSING_AUTH_HEADERNo hay header Authorization.
- 401
INVALID_API_KEYLa API key no es válida o fue revocada.
- 401
ACCOUNT_BLOCKEDLa cuenta fue bloqueada.
- 401
NO_CREDITS_LEFTNo hay créditos de email suficientes para todos los destinatarios. Cada dirección en to, cc y bcc usa 1 crédito.
- 401
DOMAIN_NOT_VALIDATEDDominio del remitente no verificado.
- 401
LISTED_SPAM_HAUSEl dominio del remitente está listado en Spamhaus.
- 401
ISP_DOMAIN_BLOCKEDNo se permite enviar desde dominios conocidos (gmail.com, outlook.com, etc).
- 401
FROM_HEADER_DOMAIN_MISMATCHDominio del header From no autorizado para este remitente.
- 401
USER_NOT_FOUNDUsuario no encontrado.
- 401
MISSING_USER_PRIVILEGESFaltan privilegios de usuario.
- 401
EMAIL_CREDITS_NOT_FOUNDError al obtener los créditos de email.
- 401
EMAIL_NOT_VALIDATEDEl email de la cuenta aún no fue verificado.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDAPI key bloqueada temporalmente por violaciones repetidas de la política.
- 429
IP_TEMPORARILY_BLOCKEDIP de la solicitud bloqueada temporalmente por violaciones repetidas de la política.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSDemasiadas solicitudes simultáneas desde esta IP. Inténtalo de nuevo en breve.
- 400
INVALID_JSONEl cuerpo de la solicitud no es un JSON válido.
- 400
MISSING_FROMEl campo from falta o está vacío.
- 400
INVALID_FROM_FORMATEl campo from debe ser una dirección de email válida.
- 400
MISSING_SENDERNAMEEl campo senderName falta o está vacío.
- 400
INVALID_SENDERNAME_FORMATEl campo senderName contiene caracteres no válidos.
- 400
MISSING_SUBJECTEl campo subject falta o está vacío.
- 400
MISSING_BODYEl campo body falta o está vacío.
- 400
MISSING_TOADDRESSEl campo to falta o está vacío.
- 400
MISSING_TOEl campo to falta o está vacío.
- 400
INVALID_TOADDRESSUna o más direcciones de destinatario están mal formadas.
- 400
TOADDRESS_LIMIT_EXCEEDEDMás de 50 destinatarios en el array to.
- 400
INVALID_CCADDRESSUna o más direcciones de cc están mal formadas.
- 400
INVALID_BCCADDRESSUna o más direcciones de bcc están mal formadas.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc y bcc juntos tienen más de 50 destinatarios únicos.
- 400
INVALID_SCHEDULED_ATscheduled_at no es una fecha válida o está en el pasado.
- 400
INVALID_SENDER_FORMATEl formato del email del remitente no es válido.
- 400
HEADER_NOT_ALLOWEDLa clave del header personalizado no está en la lista permitida (List-Unsubscribe, List-Id, X-*, etc).
- 400
INVALID_HEADER_VALUEEl valor del header contiene caracteres no válidos (CR/LF no permitidos).
- 400
DANGEROUS_ATTACHMENTUno o más adjuntos fueron bloqueados por motivos de seguridad.
- 400
INVALID_ATTACHMENTEl contenido de un adjunto no es base64 válido.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe es true pero el body no tiene placeholder de baja ([unsubscribe_url], [unsubscribe], [unsub_url] o [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDLa cuenta está restringida temporalmente.
- 403
DAILY_LIMITSe alcanzó el límite diario de envío de emails.
- 403
MARKETING_LIMIT_REACHEDSe alcanzó el límite diario de marketing del plan gratuito: 30 emails de marketing o cold outreach por día, contados por destinatario en una ventana móvil de 24 horas. La respuesta incluye limit, used, recipients y upgradeUrl. Los emails transaccionales se siguen enviando; nada queda en cola.
- 403
FORBIDDEN_HTML_CONTENTEl HTML contiene contenido activo no permitido en emails (script, iframe, form, input, button, embed, object, svg, handlers on*, enlaces javascript:, meta refresh…). La respuesta lista lo encontrado. Usa un <a> con estilos en lugar de botones o formularios.
- 403
SPAM_DETECTEDContenido del email marcado como spam. La respuesta incluye el quarantine_id y las instrucciones de liberación.
- 403
SENDER_NAME_MISMATCHSe detectaron varios nombres de remitente para la misma dirección.
- 403
FOLLOWUP_PATTERN_DETECTEDContenido del email marcado como patrón repetido de seguimiento sospechoso.
- 403
SCAM_PATTERN_DETECTEDContenido del email marcado como patrón de estafa.
- 403
SHARED_DOMAIN_REQUIRES_PAID_PLANEste dominio de envío compartido solo está disponible en los planes de pago. La respuesta indica en allowedDomains los dominios compartidos que puedes usar, además de upgradeUrl. Usa uno de ellos o tu propio dominio verificado.
- 403
ACCOUNT_SUSPENDED_SPOOFINGCuenta suspendida por intentos repetidos de suplantación del header From.
- 409
IDEMPOTENCY_IN_PROGRESSUna solicitud con la misma Idempotency-Key todavía se está procesando. Espera (Retry-After: 1) y reintenta con la misma clave.
- 422
IDEMPOTENCY_KEY_REUSEDEsta Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para cada email nuevo.
- 500
INTERNAL_SERVER_ERRORError inesperado del servidor. Inténtalo de nuevo.
- 500
PARSE_ERRORNo se pudo procesar el contenido del email (fallo de parse MIME).
- 500
PERSIST_FAILEDNo se pudo poner el email en cola (fallo de persistencia en la base de datos).
- 503
AUTH_UNAVAILABLENo se pudo validar la API key en este momento. Inténtalo de nuevo.
- 503
UNSUBSCRIBE_UNAVAILABLEServicio de enlace de baja no disponible temporalmente. Inténtalo más tarde.
Límites del plan gratuito
En el plan gratuito, el marketing y el cold outreach están limitados a 30 emails por día, contados por destinatario (un email a 5 personas cuenta como 5) en una ventana móvil de 24 horas. Los emails transaccionales no se ven afectados. Por encima del límite la solicitud se rechaza y nada queda en cola: vuelve a enviar cuando se libere la ventana o mejora tu plan.
MARKETING_LIMIT_REACHEDLo devuelve /v3.0/send cuando este email superaría el límite de marketing del plan gratuito. used es lo que ya se contó en las últimas 24 horas y recipients es cuántos sumaría este email.
{
"code": "MARKETING_LIMIT_REACHED",
"error": "Daily marketing limit reached for the free plan (30/30, 2 recipients in this email). Transactional emails still go out.",
"limit": 30,
"used": 30,
"recipients": 2,
"upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}SHARED_DOMAIN_REQUIRES_PAID_PLANSe devuelve al crear un remitente en un dominio compartido que solo está disponible en los planes de pago. allowedDomains indica los dominios compartidos que tu plan puede usar; tu propio dominio verificado siempre funciona.
{
"code": "SHARED_DOMAIN_REQUIRES_PAID_PLAN",
"error": "This shared domain is available on paid plans. Use inboxtaken.com or your own domain.",
"allowedDomains": ["inboxtaken.com"],
"upgradeUrl": "https://app.sendcorex.com/dashboard/billing"
}Reglas completas: Política de Uso Aceptable — Plan gratuito
Recepción: errores HTTP
Estos rechazan toda la solicitud. El body es { "type": "ERROR", "code": "...", "message": "..." }. Con RATE_LIMITED, espera los segundos indicados en el header Retry-After.
- 400
INVALID_JSONThe body is not {"commands":[...]} or has more than 20 commands.
- 401
MISSING_AUTH_HEADERNo Authorization header was sent.
- 401
INVALID_TOKENThe token is malformed, unknown or revoked.
- 401
TOKEN_EXPIREDThe access token has expired. Call Refresh Token and repeat the request.
- 401
INVALID_REFRESH_TOKENThe refresh token is invalid, expired, revoked or already used. Generate a new token in the dashboard.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + mailbox. Wait the number of seconds in Retry-After.
- 503
AUTH_UNAVAILABLEAuthentication is temporarily unavailable. Try again.
Recepción: errores de comando
Estos vuelven dentro del resultado del comando, con HTTP 200, así que un comando que falla no detiene a los demás de la misma solicitud. Revisa results[].type. Consulta Ejecutar comandos.
- CMD
INVALID_ARGSA required argument is missing or invalid.
- CMD
UNKNOWN_COMMANDThe command name does not exist.
- CMD
NOT_FOUNDThe message, thread or folder does not exist for this token.
- CMD
INVALID_CURSORThe cursor is malformed or belongs to another account or folder.
- CMD
ALREADY_EXISTSA folder or label with this name already exists.
- CMD
NOT_IN_TRASHdelete only works on messages in Trash or Spam. Use move to send a message to Trash first.
- CMD
SENDER_NOT_FOUNDThe sender behind the token is not registered.
- CMD
SENDER_NO_DOMAINThe sender behind the token has no domain.
- CMD
NO_CREDITSThe account has fewer email credits than recipients (1 credit per copy).
- CMD
NO_RECIPIENTThe conversation has no recipient to reply to.
- CMD
INVALID_RULEThe rule is not valid. The message says which condition or action and why.
- CMD
LIMITThe mailbox reached the limit (100 rules, 200 templates or 100 labels).
- CMD
INVALID_TOADDRESSThe to address is not a valid email.
- CMD
INVALID_CCADDRESSOne of the cc addresses is not a valid email.
- CMD
INVALID_BCCADDRESSOne of the bcc addresses is not a valid email.
- CMD
INVALID_RECIPIENTThe recipient is missing or not a valid email.
- CMD
RECIPIENT_LIMIT_EXCEEDEDto, cc and bcc together have more than 50 addresses.
- CMD
INVALID_ATTACHMENTAn attachment content is not valid base64.
- CMD
FILE_BLOCKEDA file was blocked by the security scan.
- CMD
ATTACHMENTS_TOO_LARGEThe attachments of the email add up to more than 25 MB, or the mailbox already has 500 MB of uploads waiting to be sent.
- CMD
TOO_MANY_OPEN_COMPOSESThe mailbox has 50 emails with uploads that were not sent yet. Send them, or wait for the unused ones to be deleted after 48 hours.
- CMD
ATTACHMENT_MISSINGAn uploaded attachment no longer exists (uploads not sent within 48 hours, and not used by a draft or scheduled email, are deleted). Upload it again.
- CMD
ALREADY_SENTThe compose_uid belongs to an email that was already sent.
- CMD
INVALID_TIMEsend_at is missing, less than 1 minute away or more than 1 year away.
- CMD
MISSING_SUBJECTA new email needs a subject.
- CMD
MISSING_TARGETReply and forward need the original email, and it must still exist.
- CMD
DRAFT_NOT_FOUNDThe draft does not exist anymore: it was sent, deleted, or saved again (every save returns a new draft_id).
- CMD
NOT_SCHEDULEDThe email was already sent or canceled.
- CMD
SEND_FAILEDThe send was refused. The email is back in Drafts and the message says why.
- CMD
NO_UNSUBSCRIBEThe email has no List-Unsubscribe header.
- CMD
RECIPIENT_UNSUBSCRIBEDOne or more recipients unsubscribed from this mailbox. `recipients` lists them: remove them or send again with `unsubscribe: false`.
- CMD
PAID_PLAN_REQUIREDMore than one address in `to` needs a paid plan.
- CMD
TOO_MANY_RECIPIENTS`to` has more than 30 addresses.
- CMD
INVALID_AUDIENCEThe audience is not valid: unknown group, a segment of another mailbox or a message this mailbox didn’t send.
- CMD
AUDIENCE_OVER_LIMITThe audience has more people than you can send to (up to 5,000 per email and your daily limit). `total` and `allowed` say how many.
- CMD
EMPTY_AUDIENCENobody in this audience right now.
- CMD
BEST_TIME_NEEDS_AUDIENCE`best_time` needs an `audience` and `mode: new`.
- CMD
READ_ONLY_ACCESSThe token or app has Read only access and the command writes. In the attachment upload route it is HTTP 403.
- CMD
INTERNALServer error. The detail is only written to the server log.