Skip to main content

Common Issues

Solutions to problems you might encounter when using the MAES Platform SDK.

Authentication Issues​

"Invalid or expired API key"​

Cause: The API key is incorrect, revoked, or malformed.

Solutions:

  1. Verify you're using the complete API key
  2. Check the key hasn't been revoked in the dashboard
  3. Ensure proper format in the SDK:
import { MaesClient } from '@nuvoni/maes-sdk';

// ✅ Correct
const client = new MaesClient({
  apiKey: 'sk_sandbox_aBcDeFgHiJkLmNoPqRs...',
  projectId: 'your-project-id',
});

// ❌ Wrong - missing project ID
const client = new MaesClient({
  apiKey: 'sk_sandbox_xxxxx',
});

"API key does not have access to this project"​

Cause: Using an API key from a different project.

Solution: Each project has its own API keys. Make sure you're using a key generated for the specific project you're trying to access.

Card Operation Issues​

"Card is already activated"​

Cause: Trying to activate a card that's already active.

Solution: Use enable/disable instead of activate:

const card = await client.cards.get(cardId);

if (card.status === 'new') {
  await client.cards.activate(cardId, { licensePlate, driver });
} else if (card.status === 'inactive') {
  await client.cards.enable(cardId);
}

"Card must be activated before enabling"​

Cause: Trying to enable a card with status new.

Solution: Activate the card first with license plate and driver info.

Operations not reflected in MAES portal​

Cause: Background job hasn't completed yet.

Solution:

  • Check syncStatus field on the card
  • Wait for webhook notification (card.enabled, card.disabled)
  • In sandbox, operations are instant (no real MAES connection)

Webhook Issues​

Not receiving webhook events​

Possible causes:

  1. URL not accessible — Ensure your endpoint is publicly accessible (not localhost)
  2. HTTPS required — Webhook URLs must use HTTPS
  3. Firewall blocking — Check firewall rules allow incoming requests
  4. Wrong events — Verify you've subscribed to the correct events
  5. Webhook disabled — Check if webhook was auto-disabled after failures

Debug steps:

  1. Check delivery history in the dashboard
  2. Send a test event from the dashboard
  3. Verify webhook status

Signature verification failing​

Possible causes:

  1. Wrong secret — Using old secret after rotation
  2. Parsing body first — Must use raw body for verification
  3. Encoding issues — Ensure UTF-8 encoding
// ❌ Wrong - body already parsed
app.post('/webhook', express.json(), (req, res) => {
  // req.body is already parsed, verification will fail
});

// ✅ Correct - raw body
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const event = client.webhooks.verifySignature(
    req.body.toString(),
    req.headers['x-webhook-signature'] as string,
    WEBHOOK_SECRET,
  );
});

Duplicate events received​

Cause: Events may be delivered more than once (at-least-once delivery).

Solution: Implement idempotency using the event id:

const processedEvents = new Set<string>();

async function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }
  processedEvents.add(event.id);
  // Process event...
}

Rate Limiting Issues​

Getting 429 Too Many Requests​

Solution: Implement delays between requests:

import { MaesRateLimitError } from '@nuvoni/maes-sdk';

async function enableWithRetry(cardId: string) {
  try {
    return await client.cards.enable(cardId);
  } catch (error) {
    if (error instanceof MaesRateLimitError) {
      await sleep(60000); // Wait 1 minute
      return enableWithRetry(cardId);
    }
    throw error;
  }
}

Hitting limits during batch operations​

Solution: Add delays between requests:

for (const cardId of cardIds) {
  await client.cards.enable(cardId);
  await sleep(500); // 500ms delay between requests
}

Data Sync Issues​

Cards not appearing after project creation​

Cause: Initial sync hasn't completed yet.

Solution:

  • Wait for sync.completed webhook event
  • Check project sync status in dashboard
  • Manually trigger sync if needed

Card data outdated​

Cause: Sync runs periodically, not in real-time.

Solution:

  • Check lastSyncedAt timestamp
  • Wait for next scheduled sync
  • Use webhooks for real-time updates on card operations

Environment Issues​

Operations work in sandbox but fail in production​

Possible causes:

  1. MAES credentials invalid — Check credentials in project settings
  2. MAES portal down — Check MAES portal status
  3. Card doesn't exist in MAES — Card may have been removed from MAES portal