Errores y troubleshooting

Códigos HTTP

Código	Significado	Cuándo ocurre
200	OK	Petición exitosa.
403	Forbidden	Falta o es inválida la cabecera X-Device-Id.
404	Not Found	Ruta inexistente, o moneda inválida al crear orden, o monto por debajo del mínimo, o URLs de redirección malformadas.
429	Too Many Requests	Rate limit excedido. Use Retry-After.
500	Internal Server Error	Error del backend. Reintente con backoff exponencial; si persiste, contacte soporte.

Cómo interpretar un 404 en POST /orders/

El 404 agrupa varias causas. El cuerpo de la respuesta suele indicar la concreta:

• Currency inválida — el input_currency no coincide con ningún símbolo de GET /currencies.
• Monto mínimo no alcanzado — expected_output_amount por debajo del min_amount de la moneda.
• URLs de redirección ausentes o malformadas (merchant_urlok, merchant_urlko).

Troubleshooting rápido

Recibo 403 en todas las peticiones

• Verifique que la cabecera se llama exactamente X-Device-Id (con guiones, case-insensitive en HTTP pero use la forma exacta por si acaso).
• Verifique que la key no tenga espacios al inicio/final.
• Verifique que el dispositivo no esté desactivado en el dashboard.

Recibo 404 en POST /orders/ con un símbolo que sí existe

• Llame a GET /currencies y copie el símbolo exacto. Los símbolos son granulares por red (por ejemplo USDC_POLYGON_NXTB, no solo USDC).
• Verifique mayúsculas/minúsculas.

El webhook no llega

• Revise que notification_url apunte a una URL pública (no localhost).
• Use HTTPS.
• Compruebe que su endpoint devuelve 200 rápido (< 5 s).
• Verifique el firewall de su servidor.

La firma del webhook no coincide

Causas comunes (en orden de frecuencia):

1. No decodificó la Secret Key desde hex a bytes.
2. Parseó y reserializó el body JSON (use el body crudo).
3. Añadió trailing newline al body.
4. Concatenó body + nonce en lugar de nonce + body.
5. Comparó con == en lugar de timing-safe.

Valide con los test vectors oficiales.

Consejo

Si tras verificar todo lo anterior sigue fallando, abra un ticket en support@b4bit.com incluyendo: identifier de la orden, timestamp aproximado, y la petición HTTP completa (redactando la X-Device-Id).