Common API JSON Response Errors and Their Solutions

When working with APIs, handling JSON response errors effectively is crucial for building robust applications. From malformed responses to unexpected structures, API JSON errors can occur in various forms. This article explores the most common API JSON response errors and provides practical solutions to handle them properly.

1. Malformed JSON Responses

One of the most frequent API issues is receiving malformed JSON that fails to parse. This typically happens when the API returns invalid syntax or incomplete data.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe",
      "email": "john@example.com"
    "timestamp": 1626782400
  }
}

// Implement try-catch when parsing API responses
try {
  const data = JSON.parse(responseText);
  // Process data
} catch (error) {
  console.error("Failed to parse API response:", error);
  // Handle the error appropriately
  // Consider logging the raw response for debugging
}

2. Inconsistent Error Response Structures

Many APIs use different error formats across various endpoints, making error handling challenging. Inconsistencies can appear in field names, nesting levels, or the overall structure.

// From endpoint A
{
  "error": "User not found"
}

// From endpoint B
{
  "status": "error",
  "message": "Invalid authentication token"
}

// From endpoint C
{
  "errors": [
    {
      "code": "404",
      "detail": "Resource not found"
    }
  ]
}

// Create a normalized error handler
function normalizeApiError(response) {
  // If response is an error message string
  if (typeof response.error === "string") {
    return { message: response.error, code: "unknown" };
  }
  
  // If response has status and message
  if (response.status === "error" && response.message) {
    return { message: response.message, code: "unknown" };
  }
  
  // If response follows JSON:API format with errors array
  if (Array.isArray(response.errors) && response.errors.length > 0) {
    const error = response.errors[0];
    return { message: error.detail, code: error.code };
  }
  
  // Default fallback
  return { message: "Unknown error occurred", code: "unknown" };
}

3. Unexpected NULL Values

APIs often return NULL for optional fields, which can cause issues if your code expects values to always be present.

{
  "user": {
    "id": 456,
    "name": "Jane Smith",
    "address": null,
    "phone": null
  }
}

// Use the optional chaining operator and default values
const userName = response.user?.name || "Guest";
const userAddress = response.user?.address || "No address provided";

// Or create a function to safely access nested properties
function safeGet(obj, path, defaultValue = "") {
  return path.split('.').reduce((acc, part) => 
    acc && acc[part] !== undefined && acc[part] !== null 
      ? acc[part] 
      : defaultValue
  , obj);
}

// Usage
const phoneNumber = safeGet(response, 'user.phone', 'No phone provided');

4. Empty or Missing Arrays

When an API should return a collection of items but finds none, it might return an empty array, null, or omit the field entirely.

// Case 1: Empty array
{
  "results": []
}

// Case 2: Null instead of array
{
  "results": null
}

// Case 3: Missing field entirely
{
  "status": "success"
  // "results" field is missing
}

// Always normalize arrays before processing
function getResultsArray(response) {
  // If results exists and is an array, use it
  if (response.results && Array.isArray(response.results)) {
    return response.results;
  }
  
  // In all other cases, return an empty array
  return [];
}

// Usage
const items = getResultsArray(apiResponse);
items.forEach(item => {
  // Process each item safely
});

5. Type Mismatches

API responses sometimes return data types different from what you expect, such as strings instead of numbers or booleans as strings.

{
  "user": {
    "id": "789", // String instead of number
    "active": "true", // String instead of boolean
    "score": 85.5 // Number as expected
  }
}

// Create type-casting functions
function normalizeUserData(userData) {
  return {
    id: Number(userData.id),
    active: String(userData.active).toLowerCase() === "true",
    score: Number(userData.score)
  };
}

// Usage
const normalizedUser = normalizeUserData(response.user);
console.log(typeof normalizedUser.id); // "number"
console.log(typeof normalizedUser.active); // "boolean"

6. HTTP Status Codes Not Matching Response Content

Some APIs return success status codes (200 OK) even when errors occur, putting the actual error details in the response body.

// HTTP Status: 200 OK
// Response body:
{
  "success": false,
  "error": "Insufficient permissions to access resource"
}

// Check response content regardless of HTTP status
async function fetchWithErrorHandling(url) {
  const response = await fetch(url);
  const data = await response.json();
  
  // Check for API-level errors, even with HTTP 200
  if (data.success === false || data.error) {
    throw new Error(data.error || "API returned an error");
  }
  
  return data;
}

// Usage with try/catch
try {
  const data = await fetchWithErrorHandling('/api/resource');
  // Process successful data
} catch (error) {
  // Handle both HTTP errors and API-level errors
}

7. Best Practices for Handling API JSON Errors

1. Implement comprehensive error handling: Always use try-catch blocks when parsing JSON and making API calls.
2. Normalize responses: Create utility functions to standardize different error formats from various endpoints.
3. Validate data types: Type-check important values and convert them if necessary before using them in your application.
4. Use default values: Always have fallbacks for missing or null fields.
5. Log detailed errors: Include the raw response when logging API errors to facilitate debugging.
6. Retry with exponential backoff: Implement retry mechanisms for transient errors, with increasing delays between attempts.
7. Provide user-friendly messages: Translate technical API errors into understandable messages for end-users.