Error Codes

This page documents all error codes you may encounter when using the NotiGrid API, along with common causes and solutions.

Error Response Format

All errors follow this JSON structure:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: 'to'",
    "details": {
      "field": "to",
      "expected": "string"
    },
    "request_id": "req_1234567890"
  }
}

Fields:

code - Machine-readable error code
message - Human-readable description
details - Additional context (optional)
request_id - Unique request identifier for support

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Temporary outage

Authentication Errors (401)

`invalid_api_key`

Message: "Invalid API key"

Cause: API key is malformed or doesn't exist

Solution:

Check for typos in API key
Verify key hasn't been deleted
Ensure no extra whitespace
Create a new key if needed

# Correct format
Authorization: Bearer sk_live_abc123...

# Wrong - extra space
Authorization: Bearer  sk_live_abc123...

`expired_api_key`

Message: "API key has expired"

Cause: API key has passed its expiration date

Solution:

Create a new API key
Update your application
Delete the expired key

`missing_authorization`

Message: "Missing Authorization header"

Cause: No Authorization header in request

Solution:

curl https://api.notigrid.com/v1/notifications \
  -H "Authorization: Bearer YOUR_API_KEY"

Permission Errors (403)

`insufficient_permissions`

Message: "Insufficient permissions for this operation"

Cause: API key lacks required permissions

Solution:

Check API key permissions in dashboard
Create new key with appropriate permissions
Contact admin for access

`organization_mismatch`

Message: "Resource belongs to different organization"

Cause: Trying to access resource from another organization

Solution:

Verify Organization ID is correct
Check you're using the right API key
Ensure resource belongs to your organization

Validation Errors (422)

`invalid_email`

Message: "Invalid email address"

Cause: Email format is incorrect

Solution:

// Bad
to: "not-an-email"

// Good
to: "user@example.com"

`invalid_phone`

Message: "Invalid phone number"

Cause: Phone number not in E.164 format

Solution:

// Bad
to: "1234567890"
to: "(123) 456-7890"

// Good
to: "+11234567890"

`missing_required_field`

Message: "Missing required field: {field}"

Cause: Required parameter not provided

Solution:

// Bad - missing 'to'
{
  "channel": "email",
  "body": "Hello"
}

// Good
{
  "channel": "email",
  "to": "user@example.com",
  "body": "Hello"
}

`invalid_channel`

Message: "Invalid channel type"

Cause: Unsupported channel specified

Solution:

// Bad
channel: "telegram"

// Good - supported channels
channel: "email"    // Email
channel: "sms"      // SMS
channel: "push"     // Push notification
channel: "slack"    // Slack
channel: "webhook"  // Webhook

`template_not_found`

Message: "Template not found: {template_name}"

Cause: Referenced template doesn't exist

Solution:

Check template name spelling
Verify template exists in dashboard
Create template if needed

`invalid_template_variable`

Message: "Missing required variable: {variable}"

Cause: Template requires a variable not provided

Solution:

// Template contains: Hello {{name}}

// Bad - missing 'name'
{
  "template": "welcome",
  "data": {}
}

// Good
{
  "template": "welcome",
  "data": {
    "name": "John"
  }
}

Resource Errors (404)

`notification_not_found`

Message: "Notification not found"

Cause: Notification ID doesn't exist

Solution:

Verify notification ID is correct
Check notification hasn't been deleted
Ensure you have access to this resource

`template_not_found`

Message: "Template not found"

Cause: Template doesn't exist or was deleted

Solution:

List templates: GET /v1/templates
Verify template name
Create template if needed

Rate Limit Errors (429)

`rate_limit_exceeded`

Message: "API rate limit exceeded"

Cause: Too many requests in time window

Solution:

// Implement exponential backoff
async function sendWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await send(data);
    } catch (error) {
      if (error.code === 'rate_limit_exceeded') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

See Rate Limits for details.

`notification_quota_exceeded`

Message: "Monthly notification quota exceeded"

Cause: Exceeded plan's monthly limit

Solution:

Upgrade to higher plan
Wait until quota resets
Contact sales for increase

Channel-Specific Errors

Email Errors

invalid_sender

Sender email not verified
Solution: Verify sender in dashboard

blocked_recipient

Recipient previously bounced/complained
Solution: Remove from mailing list

spam_detected

Content flagged as spam
Solution: Review content, improve formatting

SMS Errors

invalid_phone_number

Phone number invalid or unsupported
Solution: Use E.164 format, check country support

unsubscribed

Recipient opted out of SMS
Solution: Remove from SMS list

carrier_blocked

Carrier rejected message
Solution: Check content, verify sender ID

Slack Errors

channel_not_found

Slack channel doesn't exist
Solution: Verify channel name, invite bot

bot_not_in_channel

Bot not invited to channel
Solution: /invite @NotiGrid in channel

invalid_slack_token

Slack token invalid or revoked
Solution: Reconnect Slack workspace

Server Errors (500)

`internal_server_error`

Message: "An internal server error occurred"

Cause: Unexpected server issue

Solution:

Retry request with exponential backoff
If persists, contact support with request_id

`service_unavailable`

Message: "Service temporarily unavailable"

Cause: Planned maintenance or temporary outage

Solution:

Check status page: status.notigrid.com
Retry after a few minutes
Implement retry logic

Best Practices

1. Always Check Status Codes

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error);

  // Handle specific errors
  switch (error.error.code) {
    case 'rate_limit_exceeded':
      // Implement backoff
      break;
    case 'invalid_email':
      // Validate email before retry
      break;
    default:
      // Log and alert
  }
}

2. Log Request IDs

try {
  const result = await sendNotification(data);
} catch (error) {
  console.error('Error:', {
    code: error.code,
    message: error.message,
    request_id: error.request_id,  // Include for support
    timestamp: new Date().toISOString()
  });
}

3. Implement Retry Logic

async function sendWithRetry(data) {
  const retryable = [
    'rate_limit_exceeded',
    'service_unavailable',
    'internal_server_error'
  ];

  try {
    return await send(data);
  } catch (error) {
    if (retryable.includes(error.code)) {
      await sleep(1000);
      return await send(data);
    }
    throw error;
  }
}

4. Validate Before Sending

function validateNotification(data) {
  const errors = [];

  if (!data.to) errors.push('Missing recipient');
  if (!data.channel) errors.push('Missing channel');

  if (data.channel === 'email' && !isValidEmail(data.to)) {
    errors.push('Invalid email');
  }

  if (data.channel === 'sms' && !isValidPhone(data.to)) {
    errors.push('Invalid phone');
  }

  if (errors.length > 0) {
    throw new Error(errors.join(', '));
  }
}

5. Monitor Error Rates

const errorCounts = {};

function trackError(errorCode) {
  errorCounts[errorCode] = (errorCounts[errorCode] || 0) + 1;

  // Alert if high error rate
  if (errorCounts[errorCode] > 100) {
    alertAdmin(`High error rate: ${errorCode}`);
  }
}

Debugging

Enable Debug Logging

const DEBUG = process.env.DEBUG === 'true';

async function send(data) {
  if (DEBUG) {
    console.log('Sending notification:', data);
  }

  try {
    const response = await fetch(url, options);

    if (DEBUG) {
      console.log('Response status:', response.status);
      console.log('Response headers:', response.headers);
    }

    return await response.json();
  } catch (error) {
    if (DEBUG) {
      console.error('Request failed:', error);
    }
    throw error;
  }
}

Test Mode

Use test mode to debug without sending:

curl https://api.notigrid.com/v1/notifications \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Test-Mode: true" \
  -d '{
    "channel": "email",
    "to": "test@example.com",
    "body": "Test"
  }'

Returns validation errors without actually sending.

Getting Help

When contacting support about an error:

Include:

Error code and message
Request ID (from error response)
Timestamp of occurrence
Request payload (remove sensitive data)
Expected vs actual behavior

Example:

Subject: Error 422: invalid_email

Request ID: req_1234567890
Timestamp: 2025-01-16T10:30:00Z
Error: invalid_email

Request:
POST /v1/notifications
{
  "channel": "email",
  "to": "user@example.com",
  "template": "welcome"
}

Expected: Send email
Actual: Error "Invalid email address"

Support

API Status: status.notigrid.com
Documentation: docs.notigrid.com
Support: support@notigrid.com
Community: community.notigrid.com

Error Codes

On this page