Skip to Content
AI Powered Docs! 🤖 These docs are translated with AI, so keep an eye out for minor quirks. We're always improving!
TechnicalAPITroubleshooting

API Troubleshooting

This section helps you identify and resolve common issues you may encounter when working with the Metrix REST API.

1. Authentication & Access Issues

  • 403 Forbidden Error:

    • Reason 1: Incorrect or invalid API Key.
      • Solution: Re-verify your APP_ID and API_Key from the Application Settings section in the Metrix dashboard.
    • Reason 2: IP WhiteList setting in the dashboard.
      • Explanation: If you have configured an IP WhiteList for your API in the Metrix dashboard, only requests from authorized IPs will receive a response.
      • Solution: Ensure that your requests are being sent from an IP registered in the WhiteList, or review the WhiteList settings in the dashboard and temporarily disable it if necessary.

  • Exposed Server API Key:

    • Security Note: The Server API Key should never be used or exposed in client-side code (web or mobile application).
    • Solution: If your Server API Key is leaked or accidentally exposed, immediately change its type to Client in the Metrix dashboard and then create and replace it with a new API Key.

2. Data Format & Content Issues

  • 400 Bad Request Error:

    • Likely reason: Invalid JSON structure or incomplete/incorrect fields.
    • Solution:
      • Ensure your request body is valid JSON.
      • Check all mandatory fields (type, id, time, name/customName, and relevant user identifiers).
      • Verify the data type of each field (e.g., time and birthday as a Long number, revenue as a Double) according to the documentation.

  • Events are not displayed in the dashboard, but a 200 OK code was received:

    • Explanation: Receiving a 200 OK code only signifies that the request was successfully sent to the server, and does not necessarily mean the event was processed correctly.
    • Possible reasons:
      • Duplicate Event: If you send an event with a consistent metrixUserId and the same time, the Metrix system will automatically detect it as a duplicate and drop it.
      • Incorrect/incomplete customUserId or metrixUserId.
      • Invalid or empty name or customName.
    • Solution:
      • Ensure you are sending a unique id for each message and a correct, logical time for each event.
      • Verify the correctness of the customUserId and metrixUserId identifiers.
      • Confirm the accuracy of name or customName and that it follows the Taxonomy.

3. Messaging Channel Issues

  • Message not received (Push/SMS/Email):
    • Solution: Before testing via the API, you must have successfully tested sending a message for the desired channel (e.g., Push Notification or SMS) through the Metrix dashboard. This ensures that your channel settings in the dashboard are correct.

4. Server Connectivity Issues

  • Unable to connect to the Metrix Endpoint:

    • Possible reasons: Your server’s firewall, network issues, or failed DNS resolution.
    • Solutions:
      • Check DNS Status: Make sure your server can resolve the entry.metrix.ir address to its corresponding IP. You can use the dig or nslookup command in your server’s terminal: 
        dig entry.metrix.ir
        or 
        nslookup entry.metrix.ir
      • Test Connection (Ping/Telnet/cURL): Check if your server can access the Metrix Endpoint.
        • With Telnet (for port 443): 
          telnet entry.metrix.ir 443
          If the connection is successful, you will see a blank page or a “Connected” message. Otherwise, there is a firewall or network issue.
        • With cURL (a simple connection test): 
          curl -v https://entry.metrix.ir/
          This command will show connection details and can help identify SSL/TLS or network problems.
      • Check Server Firewall: Ensure that your server’s firewall allows access to port 443 (HTTPS) and the entry.metrix.ir domain.
      • Check Network Logs: Examine your server’s network logs for any connection errors or rejected requests.

  • Server Errors (5xx Server Error) or Timeout:

    • Possible reasons: These errors usually indicate temporary issues on the Metrix server side or more widespread network problems.
    • Solution: The issue may be temporary. Retry the request (using a Retry and Exponential Backoff mechanism). If the problem persists, contact support.

5. Contacting Support

If you are still experiencing issues after performing the checks above, please contact the Metrix support team. To expedite the troubleshooting process, be sure to provide the following information:

  • Your APP_ID.
  • The full curl request related to the issue (including Headers and Body).
  • The response received from the Metrix server (including the HTTP status code and response body).
  • The exact date and time the issue occurred (UTC).
  • Any relevant error messages from your server logs.
Last updated on
FAQsGetting Started