Error Handling

When something goes wrong with a SALZ API request, the response includes a clear error message and an appropriate HTTP status code. This page covers every error you might encounter and how to handle them.

Error Response Format

All errors follow the same JSON structure:

{
  "error": "Human-readable description of the problem",
  "success": false
}

The error field always contains a string describing what went wrong. The success field is always false for error responses.

Error Codes

400 Bad Request

The request body is malformed or missing required fields.

Missing text field:

{
  "error": "Text is required",
  "success": false
}

Text too long:

{
  "error": "Text exceeds maximum length of 10000 characters",
  "success": false
}

Invalid JSON:

{
  "error": "Invalid JSON in request body",
  "success": false
}

Fix: Check that your request body is valid JSON and includes the text field within the character limit.

401 Unauthorized

The API key is missing, invalid, or revoked.

{
  "error": "Invalid or missing API key",
  "success": false
}

Fix: Verify that your Authorization header is formatted as Bearer YOUR_API_KEY with the correct key. Check that the key has not been revoked in your dashboard.

403 Forbidden

The API key is valid but does not have permission to access this resource.

{
  "error": "Access denied",
  "success": false
}

Fix: This typically indicates an account issue. Check your account status in the dashboard.

429 Too Many Requests

You have exceeded the rate limit or monthly quota.

Rate limit exceeded:

{
  "error": "Rate limit exceeded. Try again in 45 seconds.",
  "success": false
}

Monthly quota exceeded:

{
  "error": "Monthly API call quota exceeded. Upgrade your plan or wait for the next billing period.",
  "success": false
}

Fix: Implement exponential backoff for rate limits. For quota limits, upgrade your plan or wait for the next billing period.

500 Internal Server Error

Something went wrong on the SALZ server.

{
  "error": "Internal server error",
  "success": false
}

Fix: This is not your fault. Retry the request with exponential backoff. If the error persists, check the SALZ status page or contact support.

Retry Strategy

Not all errors should be retried:

Exponential Backoff Implementation

async function salzOptimize(text) {
  const maxRetries = 3;

  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch('https://add-salz.io/api/v1/optimize', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SALZ_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ text }),
    });

    if (response.ok) {
      return await response.json();
    }

    // Do not retry client errors (except 429)
    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
      const data = await response.json();
      throw new Error(`SALZ API error ${response.status}: ${data.error}`);
    }

    // Retry on 429 and 5xx
    if (i < maxRetries - 1) {
      const delay = Math.pow(2, i) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }

  throw new Error('SALZ API request failed after retries');
}

Troubleshooting Checklist

If your requests are failing:

1. Check the HTTP status code. It tells you the category of error.
2. Read the error message. It describes the specific problem.
3. Verify your API key. Make sure it is correct and not revoked.
4. Check your request format. Valid JSON with a text field.
5. Check your rate limits. Look at X-RateLimit-Remaining in previous responses.
6. Check the text length. Stay within the character limit for your plan.
7. Try the playground. If the playground works but the API does not, the issue is in your request construction.

Logging Recommendations

Log the following for every SALZ API call to make debugging easier:

• HTTP status code
• Error message (from the response body)
• Request timestamp
• Text length (not the text itself, for privacy)
• Rate limit headers