API Error Codes & Handling

When an API request fails, Data Mammoth returns a structured error response with a status code, error code, and human-readable message. This guide covers all error codes, their meanings, and how to handle them in your application.

Error Response Format

All API errors follow this structure:

{
  "error": {
    "code": "not_found",
    "message": "The requested server was not found.",
    "status": 404,
    "details": {}
  }
}

HTTP Status Codes

Client Errors (4xx)

Server Errors (5xx)

Common Error Scenarios

Validation Errors (422)

When submitted data fails validation, the details field lists specific issues:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "status": 422,
    "details": {
      "name": ["Name is required."],
      "plan": ["The selected plan is not available in the chosen region."],
      "os": ["The selected OS image is not valid."]
    }
  }
}

Handling: Parse the details object and fix each field-level error.

Authentication Errors (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key or token expired.",
    "status": 401
  }
}

Handling: Check the API key, refresh JWT tokens, or generate a new key.

Resource Conflicts (409)

{
  "error": {
    "code": "conflict",
    "message": "Cannot stop a server that is already stopped.",
    "status": 409
  }
}

Handling: Check the current resource state before performing actions.

Rate Limiting (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "status": 429,
    "details": {
      "retry_after": 30
    }
  }
}

Handling: Wait for the retry_after period, then retry. See API Rate Limits & Best Practices.

Error Handling Best Practices

1. Always Check the Status Code

response = requests.get(url, headers=headers)
if response.status_code == 200:
    data = response.json()["data"]
elif response.status_code == 429:
    retry_after = response.json()["error"]["details"]["retry_after"]
    time.sleep(retry_after)
elif response.status_code == 401:
    refresh_token()
else:
    error = response.json()["error"]
    log_error(error["code"], error["message"])

2. Implement Retry Logic for Transient Errors

Retry on 429, 500, 502, 503, and 504 errors with exponential backoff. Do not retry on 400, 401, 403, 404, or 422 errors — these indicate issues that need to be fixed.

3. Log Errors for Debugging

Log the full error response (code, message, details) along with the request that caused it. This makes troubleshooting much easier.

4. Display User-Friendly Messages

Use the message field for user-facing error messages, but consider mapping code values to your own messages for a better user experience.

5. Handle Unexpected Errors

Always include a default error handler for unexpected status codes:

else:
    print(f"Unexpected error: {response.status_code}")
    print(response.text)

What to Do Next

• API Rate Limits & Best Practices — Handle rate limiting.
• API Pagination & Filtering — Navigate results efficiently.
• API Authentication — Fix authentication errors.
• How to Submit a Support Ticket — Report persistent API issues.