Error Handling

API responses follow a standardized JSON format containing a code field and a data field. A successful request returns a code of 200, with the data field populated according to the specific endpoint's requirements. For all requests, the code field reflects a custom error code (e.g., 9001), and the data field may contain additional details about the error.

Response Format

Success Response

{
  "code": 200,
  "data": {
    // Response data here
  }
}

Error Response

{
  "code": 4001,
  "message": "Invalid AuthKey",
  "data": {
    // Additional error details
  }
}

HTTP Standard Error Codes

Code	Description	HTTP Status	Resolution
200	Success	200 OK	N/A - Request succeeded
204	No Content	204	Verify request parameters
400	Bad Request	400	Verify request parameters
429	Rate Limit exceeded	429	Retry after 1 minute
500	Internal Server Error	500	Retry later or contact support

RapidMule Custom Error Codes

Code	Description	HTTP Status	Resolution
1001	Payload is null	400	Check the request payload and method
1002	Invalid Player	400	Check if the player exists
2601	Duplicate Action	400	Check the action result by ReferenceID
4001	Invalid AuthKey	401	Check the auth header
4003	AuthKey and request origin mismatch	400	Use correct AuthKey
5002	PlayerId already exists	200	Use different PlayerId or update existing player
5003	PlayerId does not exist / must be at least 8 characters	400/200	Use valid PlayerId
9001	Insufficient funds to commit the action	400	N/A
9004	Bundle/Transaction does not exist	400	Use valid ID

Common Error Scenarios

Authentication Errors

AuthKey Issues

Error 4001 - Invalid AuthKey

This error occurs when:

• The API key is missing from the Authorization header
• The API key is incorrect or expired
• The Authorization header format is invalid

Resolution:

Authorization: Bearer YOUR_VALID_API_KEY

Player Management Errors

Player ID Requirements

Error 5003 - PlayerId does not exist / must be at least 8 characters

Player IDs must:

• Be at least 8 characters long
• Exist in the system before performing actions
• Be unique across your account

Valid Player ID Examples:

• user-12345
• player-abc123
• customer-xyz789

Action Processing Errors

Duplicate Prevention

Error 2601 - Duplicate Action

This error occurs when trying to submit an action with a referenceId that has already been processed.

Resolution:

• Check if the action was already successful
• Use a unique referenceId for each action
• Implement proper idempotency handling in your code

Error Handling Best Practices

1. Always Check Response Codes

const response = await fetch('/api/actions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(actionData)
});

const result = await response.json();

if (result.code !== 200) {
  console.error('API Error:', result.code, result.message);
  // Handle error appropriately
}

2. Implement Retry Logic for Transient Errors

async function makeApiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const result = await response.json();
      
      if (result.code === 200) {
        return result;
      }
      
      // Don't retry for client errors (4xx)
      if (result.code >= 400 && result.code < 500) {
        throw new Error(`Client Error: ${result.code}`);
      }
      
      // Retry for server errors (5xx) or rate limits
      if (i === maxRetries - 1) {
        throw new Error(`Server Error after ${maxRetries} retries`);
      }
      
      // Wait before retrying
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
      
    } catch (error) {
      if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

3. Log Errors for Debugging

function handleApiError(error, context) {
  console.error('API Error Context:', {
    error: error.message,
    code: error.code,
    context: context,
    timestamp: new Date().toISOString()
  });
  
  // Send to your error tracking service
  // errorTracker.captureException(error, { extra: context });
}

Getting Help

If you encounter errors that aren't covered in this documentation:

1. Check the error code against the tables above
2. Verify your request format matches the API specification
3. Contact support with:
   • The complete error response
   • Your API key (masked)
   • The request that caused the error
   • Your application's environment details