Troubleshooting Guide

401 Unauthorized Errors

If you're receiving 401 Unauthorized errors, there's an issue with your API authentication.

Possible Causes:

• Invalid API key or token
• Expired API token
• Using a sandbox key in production (or vice versa)
• Missing or improperly formatted Authorization header

Solutions:

• Verify your API key is correct and active in the dashboard
• Ensure the Authorization header is properly formatted: Authorization: Bearer YOUR_API_KEY
• Check that you're using the correct environment key (sandbox vs. production)
• Generate a new API key if necessary

403 Forbidden Errors

A 403 Forbidden error indicates that your authentication was successful, but you don't have permission to access the requested resource.

Possible Causes:

• Your account hasn't been approved for data furnishing yet
• You're trying to access a feature not included in your plan
• Your account has been suspended

Solutions:

• Check your account status in the dashboard
• Verify your subscription plan includes the feature you're trying to use
• Contact support if you believe this is an error

422 Unprocessable Entity Errors

A 422 error indicates that your request was well-formed but contains validation errors that prevent processing.

Common Validation Errors:

Troubleshooting Tips:

• Use our validation tool to pre-validate your data
• Start with a small batch of data to identify common issues
• Review the error response details, which include the record index and specific field causing the error
• Consult the API Reference for detailed field requirements

429 Too Many Requests Errors

A 429 error indicates that you've exceeded the API rate limits.

Rate Limits:

• Production: 10 requests per minute, up to 1,000 records per request
• Sandbox: 5 requests per minute, up to 100 records per request

Solutions:

• Implement retry logic with exponential backoff
• Check the X-RateLimit-Reset header to know when to retry
• Batch requests to maximize efficiency (send more records per request)
• Spread out your submissions over time
• Contact support if you need higher rate limits

async function submitWithRetry(data, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await apiClient.post('/submit-metro2-data', data);
      return response.data;
    } catch (error) {
      if (error.response?.status === 429) {
        // Get reset time from headers or use exponential backoff
        const resetTime = error.response.headers['x-ratelimit-reset'] || 0;
        const delayMs = resetTime ?
          (new Date(resetTime).getTime() - Date.now()) :
          Math.pow(2, retries) * 1000;

        console.log(`Rate limited. Retrying in ${delayMs}ms`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
        retries++;
      } else {
        // For other errors, don't retry
        throw error;
      }
    }
  }

  throw new Error('Max retries exceeded');
}

Batch Processing Issues

Issues related to submitting and tracking large batches of data.

Symptoms:

• Long processing times
• Batch status stuck in "processing"
• Missing or incomplete batch results

Solutions:

• Use the /batch-status/{batch_id} endpoint to check batch status
• Implement webhook notifications for batch completion
• Break very large submissions into smaller batches (500-1000 records each)
• Allow sufficient processing time (larger batches can take several minutes)

Account Linking Issues

Problems with account history continuity after account number changes.

Symptoms:

• Account history appears to reset after account number change
• Duplicate accounts appearing on credit reports
• Loss of account age/history

Solutions:

• Use the L1 segment when reporting account number changes
• Report the L1 segment only once, then use the new account number for subsequent reports
• Ensure both the old and new account numbers are accurate in the L1 segment
• See our Account Number Changes guide for detailed instructions