Skip to main content

​
Error Response Format

All errors follow a consistent JSON format: 
{
  "error": "error_code",
  "message": "Human-readable description"
}

​
HTTP Status Codes

CodeMeaningAction
200SuccessProcess the response
201CreatedResource created successfully
400Bad RequestFix the request body/params
401UnauthorizedCheck your API key or token
403ForbiddenEvent type not allowed or insufficient scope
404Not FoundResource doesn’t exist
429Rate LimitedBack off and retry after delay
500Server ErrorRetry with exponential backoff

​
Rate Limiting

​
Limits

Endpoint GroupLimit
Partner events (/api/partner/*)30 requests/min per IP
General API (/api/rewards/*)100 requests/min per IP

​
Handling 429 Responses

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please try again later."
}

async function publishEventWithRetry(event, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await sleep(retryAfter * 1000);
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

​
Common Errors

​
Partner Events

ErrorCauseFix
Missing X-API-Key headerNo API key in requestAdd X-API-Key header
Invalid API keyKey doesn’t match any active partnerCheck key, ensure partner is active
Event type not allowedEvent type not in partner’s allowlistContact MG Digital to add the event type
user_id and event_type are requiredMissing required fieldsInclude both fields in request body

​
Cashback

ErrorCauseFix
Insufficient pointsUser doesn’t have enough pointsShow balance to user before attempting
Maximum X cashback redemptions per day exceededDaily limit hitWait until tomorrow
Daily cashback limit would be exceededAmount exceeds daily GHS capReduce points amount
Please wait X minutesCooldown period activeWait the specified time

​
Best Practices

1

Validate before sending

Check user balance client-side before attempting redemptions to avoid unnecessary API calls.
2

Use idempotency keys

Always include reference_id in event metadata to prevent double-awarding on retries.
3

Implement exponential backoff

For 429 and 500 errors, wait 1s, 2s, 4s, 8s between retries.
4

Log API responses

Store response bodies for debugging. Include event_id in your logs for cross-referencing with MG Digital support.