Error Handling

The Sabdasakha API uses standard HTTP status codes and returns structured error responses.

HTTP Status Codes

Code	Meaning
`200`	Success
`400`	Bad Request - Invalid parameters
`404`	Not Found - Word not in dictionary
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Errors

Word Not Found (404)

When a word isn't in the dictionary, the API returns helpful suggestions:

Request:

curl "https://sabdasakha.com/api/v1/dictionary/word/नेपाळ"

Response (404):

{
  "error": {
    "code": "WORD_NOT_FOUND",
    "message": "Word 'नेपाळ' not found in dictionary"
  },
  "similar_words": ["नेपाल", "नेपाली"]
}

Using Similar Words

The similar_words array contains up to 5 suggestions. Use these to help users find the correct word.

Invalid Request (400)

Missing or invalid parameters:

Request:

curl "https://sabdasakha.com/api/v1/dictionary/suggest"
# Missing required 'q' parameter

Response (400):

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'q' is missing"
  }
}

Rate Limit Exceeded (429)

Too many requests in a short period:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "retry_after": 60
  }
}

See Rate Limits for handling strategies.

Handling Errors in Code

Python

import requests

def lookup_word(word):
    response = requests.get(f"https://sabdasakha.com/api/v1/dictionary/word/{word}")

    if response.status_code == 200:
        return response.json()

    elif response.status_code == 404:
        data = response.json()
        suggestions = data.get("similar_words", [])
        print(f"Word not found. Did you mean: {', '.join(suggestions)}?")
        return None

    elif response.status_code == 429:
        retry_after = response.json().get("error", {}).get("retry_after", 60)
        print(f"Rate limited. Retry after {retry_after} seconds.")
        return None

    else:
        print(f"Error: {response.status_code}")
        return None

JavaScript

async function lookupWord(word) {
  const response = await fetch(
    `https://sabdasakha.com/api/v1/dictionary/word/${word}`
  );

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

  const error = await response.json();

  if (response.status === 404) {
    const suggestions = error.similar_words || [];
    console.log(`Word not found. Did you mean: ${suggestions.join(", ")}?`);
    return null;
  }

  if (response.status === 429) {
    const retryAfter = error.error?.retry_after || 60;
    console.log(`Rate limited. Retry after ${retryAfter} seconds.`);
    return null;
  }

  throw new Error(`API error: ${response.status}`);
}

Best Practices

Always check status codes - Don't assume success
Use similar_words - Help users find correct spellings
Implement retry logic - Handle transient failures gracefully
Log errors - Track issues for debugging
Show user-friendly messages - Don't expose raw error codes to end users