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

> Discover what happens when an unsupported language code is used for keyword data APIs. Learn about the 400 Bad Request error and how to avoid it with Open SEO.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/rank-tracking.ts) at line 58 and [`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts) at line 31, the `languageCode` field uses the `.refine()` method:

```typescript
.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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```json
{
  "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"`:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts)
- Zod schemas in [`src/types/schemas/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/rank-tracking.ts) and [`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/keyword-locations.ts); the rank-tracking schema at line 58 in [`src/types/schemas/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/rank-tracking.ts); and the project schema at line 31 in [`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts). These files work together to enforce validation across all keyword-data workflows.