Skip to main content

Error Handling

This section covers common error scenarios and how to handle them.

Common Error Scenarios​

Invalid Signature (400 Bad Request)​

Error Message: "Invalid payload signature. The request signature does not match the expected signature."

Possible Causes:

  • Incorrect API key used for signature generation
  • JSON serialization format doesn't match (whitespace, property order)
  • Signature not Base64 encoded correctly
  • Missing or incorrect X-B1LINK-Signature header

Solution:

  • Verify you're using the correct API key
  • Ensure JSON is serialized exactly as: {"Id":"<guid>","ErpVendorNumber":"<vendor-number>"}
  • Double-check Base64 encoding of the HMAC result

Missing Signature Header (400 Bad Request)​

Error Message: Request validation error

Possible Causes:

  • X-B1LINK-Signature header is missing
  • Header name is misspelled

Solution:

  • Ensure the header is named exactly: X-B1LINK-Signature
  • Check that the header is included in the request

Invalid Event ID (404 Not Found)​

Error Message: "Could not find OnboardingRequestErpEvent '<id>'"

Possible Causes:

  • The event ID doesn't exist
  • The event ID was already processed
  • The event ID is for a different company

Solution:

  • Verify you're using the correct event ID from the webhook call
  • Check that the event hasn't already been processed

Malformed JSON (400 Bad Request)​

Possible Causes:

  • Invalid JSON syntax
  • Missing required fields
  • Incorrect data types

Solution:

  • Validate JSON syntax before sending
  • Ensure all required fields are present
  • Verify data types match the specification

Troubleshooting Guide​

1. Signature Verification Fails​

  • Use the code examples in Code Examples to verify your signature generation
  • Log the exact JSON string you're signing (without the API key)
  • Compare your Base64-encoded signature with a known-good example

2. Event Not Found​

  • Verify the event ID from the original webhook call
  • Check if the event was already processed
  • Contact B1Link support if the event ID is correct but not found

3. Network Issues​

  • Ensure your system can reach the B1Link API endpoint
  • Check firewall rules and network connectivity
  • Verify SSL/TLS certificates are valid

Retry Logic​

When implementing retry logic:

  • Use exponential backoff for retries
  • Don't retry on 400 Bad Request (fix the issue first)
  • Retry on 500 Internal Server Error (server-side issues)
  • Retry on network timeouts
  • Set a maximum retry count (e.g., 3 attempts)
  • Log all retry attempts for debugging

Next Steps​