From 2f54b76f00d033bdb7aa175e9032b6ccd6bba215 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Tue, 8 Sep 2026 17:41:14 +0200
Subject: [PATCH] docs: show how to select API error language

---
 README.es.md                     | 19 +++++++++++++++++
 README.md                        | 19 +++++++++++++++++
 tests/Http/ErrorHandlingTest.php | 36 ++++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+)

diff --git a/README.es.md b/README.es.md
index 0a89ee8..889d7ba 100644
--- a/README.es.md
+++ b/README.es.md
@@ -200,6 +200,25 @@ try {
 - `Facturapi\\Exceptions\\Facturapi_Exception` está deprecada en v4 y se eliminará en v5.
 - Usa `Facturapi\\Exceptions\\FacturapiException`.
 
+## Idioma de los errores de la API
+
+En API V2 puedes solicitar mensajes de error en inglés con `Accept-Language`. Usa la configuración existente del cliente:
+
+```php
+use Facturapi\Facturapi;
+use GuzzleHttp\Client;
+
+$facturapi = new Facturapi('YOUR_API_KEY', [
+    'httpClient' => new Client([
+        'headers' => ['Accept-Language' => 'en'],
+        'timeout' => 360,
+        'connect_timeout' => 3,
+    ]),
+]);
+```
+
+Usa `es` para español. También se aceptan variantes como `en-US` y preferencias como `en;q=0.9, es;q=0.5`. Sin el header o sin un idioma compatible, la API usa español. La preferencia se aplica a todas las solicitudes de esta instancia; usa instancias separadas si necesitas varios idiomas. Los códigos no cambian y los mensajes externos SAT/PAC y los mensajes legacy no catalogados conservan su idioma original. La localización depende del soporte de API V2 en el servidor; no traduce errores locales del SDK.
+
 ## Documentación 📚
 
 Documentación completa: [https://docs.facturapi.io](https://docs.facturapi.io)
diff --git a/README.md b/README.md
index c5ffd4f..43b7428 100644
--- a/README.md
+++ b/README.md
@@ -200,6 +200,25 @@ try {
 - `Facturapi\\Exceptions\\Facturapi_Exception` is deprecated in v4 and will be removed in v5.
 - Use `Facturapi\\Exceptions\\FacturapiException`.
 
+## API error language
+
+For API V2, request English error messages with `Accept-Language` using the existing client configuration:
+
+```php
+use Facturapi\Facturapi;
+use GuzzleHttp\Client;
+
+$facturapi = new Facturapi('YOUR_API_KEY', [
+    'httpClient' => new Client([
+        'headers' => ['Accept-Language' => 'en'],
+        'timeout' => 360,
+        'connect_timeout' => 3,
+    ]),
+]);
+```
+
+Use `es` for Spanish. Regional variants such as `en-US` and preferences such as `en;q=0.9, es;q=0.5` are also supported. Missing or unsupported language preferences fall back to Spanish. The setting applies to all requests from this instance; use separate instances for different languages. Codes remain unchanged, and external SAT/PAC messages and uncataloged legacy messages retain their original language. Localization requires server-side API V2 support; it does not translate local SDK errors.
+
 ## Documentation 📚
 
 Full docs: [https://docs.facturapi.io](https://docs.facturapi.io)
diff --git a/tests/Http/ErrorHandlingTest.php b/tests/Http/ErrorHandlingTest.php
index 61df2e0..d0a4653 100644
--- a/tests/Http/ErrorHandlingTest.php
+++ b/tests/Http/ErrorHandlingTest.php
@@ -4,6 +4,11 @@
 
 namespace Facturapi\Tests\Http;
 
+use Facturapi\Facturapi;
+use GuzzleHttp\Client;
+use GuzzleHttp\Handler\MockHandler;
+use GuzzleHttp\HandlerStack;
+use GuzzleHttp\Middleware;
 use Facturapi\Exceptions\FacturapiException;
 use Facturapi\Resources\Invoices;
 use Facturapi\Tests\Support\FakeHttpClient;
@@ -12,6 +17,37 @@
 
 final class ErrorHandlingTest extends TestCase
 {
+    public function testGuzzleDefaultLanguageHeaderIsSentWithSdkAuthentication(): void
+    {
+        $history = [];
+        $stack = HandlerStack::create(new MockHandler([
+            new Response(401, ['Content-Type' => 'application/json'], json_encode([
+                'message' => 'The provided API key is invalid.',
+                'code' => 'api_key_invalid',
+                'status' => 401,
+            ])),
+        ]));
+        $stack->push(Middleware::history($history));
+        $facturapi = new Facturapi('sk_test_123', [
+            'httpClient' => new Client([
+                'handler' => $stack,
+                'headers' => ['Accept-Language' => 'en-US'],
+                'timeout' => 360,
+                'connect_timeout' => 3,
+            ]),
+        ]);
+
+        try {
+            $facturapi->Invoices->retrieve('inv_123');
+            self::fail('Expected FacturapiException');
+        } catch (FacturapiException $exception) {
+            self::assertSame('The provided API key is invalid.', $exception->getMessage());
+            self::assertSame('api_key_invalid', $exception->getErrorCode());
+        }
+        self::assertSame('en-US', $history[0]['request']->getHeaderLine('Accept-Language'));
+        self::assertSame('Basic ' . base64_encode('sk_test_123:'), $history[0]['request']->getHeaderLine('Authorization'));
+    }
+
     public function testApiErrorShapeIsFullyAvailableOnException(): void
     {
         $errorBody = [