What Happens When an Unsupported Language Code Is Used for Keyword Data APIs

When an unsupported language code is submitted to Open SEO's keyword endpoints, the request is immediately rejected with a 400 Bad Request and a specific "Unsupported language code" validation error, preventing any external API calls.

Open SEO (every-app/open-seo) performs strict input validation on all language codes before processing keyword data requests. This validation ensures that only supported locale codes reach external providers like DataForSEO, protecting API credits and maintaining data integrity.

How Open SEO Validates Language Codes

The Zod Schema Layer

Open SEO uses Zod schemas to enforce input validation across its keyword-related endpoints. In src/types/schemas/rank-tracking.ts at line 58 and src/types/schemas/projects.ts at line 31, the languageCode field uses the .refine() method:

.refine(isSupportedLanguageCode, "Unsupported language code")

This refinement triggers validation against a whitelist of accepted language codes before any business logic executes.

The isSupportedLanguageCode Helper

The core validation logic resides in src/shared/keyword-locations.ts at line 775. The isSupportedLanguageCode function returns true only for language codes present in the built-in location/language map. According to test cases in src/shared/keyword-locations.test.ts (lines 55-62), valid codes include "en" and "zh-TW", while values like "english" or "en-US" are rejected as unsupported.

What Happens When Validation Fails

Immediate Zod Validation Failure

When a client submits a request containing an unsupported language code, the Zod schema validation fails immediately. The .refine() call returns a validation error object containing the message "Unsupported language code". This failure occurs during the request parsing phase, before the request reaches any service-layer logic.

The 400 Bad Request Response

Following validation failure, the server's error-handling middleware intercepts the request and returns a 400 Bad Request status. The response payload includes structured error details:

{
  "error": "ValidationError",
  "message": "Unsupported language code",
  "details": [
    {
      "path": ["languageCode"],
      "message": "Unsupported language code"
    }
  ]
}

This clear error message allows developers to identify and correct the invalid parameter quickly.

Protection of External API Resources

Because validation occurs at the schema level within the application's request pipeline, no calls are made to external keyword providers such as DataForSEO. This early rejection mechanism prevents wasted API credits and reduces unnecessary network latency for malformed requests.

Example: Submitting an Invalid Language Code

The following request attempts to use the unsupported code "english" instead of the standardized "en":

await fetch("/api/keyword-data/rank-check", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    keyword: "open seo",
    locationCode: 1024,
    languageCode: "english",   // unsupported format
  }),
})
  .then((r) => r.json())
  .then(console.log);

The server responds immediately with the validation error shown above, never processing the keyword check against external data sources.

Summary

• Validation occurs via the isSupportedLanguageCode helper in src/shared/keyword-locations.ts
• Zod schemas in src/types/schemas/rank-tracking.ts and src/types/schemas/projects.ts enforce the check using .refine()
• Unsupported language codes trigger an immediate 400 Bad Request with the message "Unsupported language code"
• External DataForSEO APIs are never called for requests containing invalid language codes

Frequently Asked Questions

What HTTP status code does Open SEO return for unsupported language codes?

The API returns a 400 Bad Request status code. The response includes a JSON payload with error: "ValidationError" and message: "Unsupported language code", along with specific path details identifying the languageCode field as the source of the failure.

Which specific language codes are supported by Open SEO?

According to the test suite in src/shared/keyword-locations.test.ts, the validator accepts standardized codes such as "en" and "zh-TW". However, it rejects verbose language names like "english" or locale-specific formats containing country codes like "en-US". The complete whitelist is defined in the location map at src/shared/keyword-locations.ts.

Does an invalid language code trigger charges from external keyword providers?

No. Because the isSupportedLanguageCode validation executes within the Zod schema layer before request handling reaches the service logic, invalid requests are rejected before any calls to external providers like DataForSEO occur. This prevents unnecessary API consumption and associated costs.

Where is the language code validation implemented in the Open SEO codebase?

The validation logic is implemented in three key locations: the isSupportedLanguageCode function defined at line 775 in src/shared/keyword-locations.ts; the rank-tracking schema at line 58 in src/types/schemas/rank-tracking.ts; and the project schema at line 31 in src/types/schemas/projects.ts. These files work together to enforce validation across all keyword-data workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}