Troubleshooting

This guide covers common issues you might encounter when using the Gerra API and provides solutions to help you resolve them.

Authentication Issues

Invalid API Key

Problem: 401 Unauthorized response with message "Invalid API key"

Solution:

• Verify your API key is correct and hasn't expired
• Ensure you're using the correct header format: gerra-api-key: YOUR_TOKEN
• Check if your token has the necessary permissions

Rate Limiting

Problem: 429 Too Many Requests response

Solution:

• Implement exponential backoff in your requests
• Reduce the frequency of API calls
• Contact support to request a rate limit increase if needed

Connection Issues

Mecha Not Available

Problem: 404 Not Found when referencing a mecha_id

Solution:

• Verify the mecha_id is correct
• Check if the mecha is online in the dashboard
• Ensure your account has access to the requested mecha

Timeout Errors

Problem: Request times out or returns 504 Gateway Timeout

Solution:

• Check your network connection
• Verify the mecha is powered on and connected
• Increase your client timeout settings for long-running operations

Command Execution Issues

Invalid Movement Parameters

Problem: 400 Bad Request with "Invalid movement parameters" message

Solution:

• Ensure coordinates are within the mecha's operational range
• Verify the JSON format of your waypoints is correct
• Check that speed values are within acceptable limits

Command Rejected

Problem: 422 Unprocessable Entity response

Solution:

• The mecha might be in an incompatible state for the command
• Try initializing the mecha before sending commands
• Check diagnostic endpoints for current mecha state

Diagnostic Tips

If you're experiencing issues, use the diagnostic endpoints to get more information:

curl "https://api.gerra.com/mecha/diagnostic/status?mecha_id=MECHA_ID" \
  -H "gerra-api-key: YOUR_TOKEN"

The response will include the current state of the mecha, any error conditions, and diagnostic information that can help identify the issue.

WebSocket Connection Issues

Connection Refused

Problem: WebSocket connection is refused or disconnects immediately

Solution:

• Verify your authentication token is included in the connection request
• Check if your firewall is blocking WebSocket connections
• Ensure you're using the correct WebSocket URL

Unexpected Disconnections

Problem: WebSocket connection drops unexpectedly

Solution:

• Implement reconnection logic with exponential backoff
• Handle ping/pong messages to keep the connection alive
• Check your network stability and connection quality

Still Having Issues?

If you've tried these solutions and are still experiencing problems:

1. Check the API Reference for detailed endpoint documentation
2. Review recent updates in the Changelog
3. Contact support at support@gerra.com with error details and your mecha_id