From bb06a14ff55d53fbc0490549d7b08231446d7cda Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Thu, 16 Jul 2026 19:52:26 +0200
Subject: [PATCH 1/2] feat: expose documented API error codes

---
 README.es.md                          |   7 +-
 README.md                             |   7 +-
 VERSION.md                            |   4 +-
 composer.json                         |   5 +-
 src/ErrorCodes.php                    | 279 ++++++++++++++++++++++++++
 src/Exceptions/FacturapiException.php |  11 +
 src/Facturapi.php                     |   1 +
 tests/Http/ErrorHandlingTest.php      |  17 +-
 8 files changed, 315 insertions(+), 16 deletions(-)
 create mode 100644 src/ErrorCodes.php

diff --git a/README.es.md b/README.es.md
index 0a89ee8..5d346e9 100644
--- a/README.es.md
+++ b/README.es.md
@@ -175,18 +175,23 @@ En respuestas no-2xx, el SDK lanza `Facturapi\Exceptions\FacturapiException`.
 La excepción incluye:
 - `getMessage()`: mensaje del API cuando está disponible.
 - `getStatusCode()`: código HTTP.
+- `getApiErrorCode()`: código raíz documentado de V2 cuando está disponible.
 - `getErrorData()`: payload JSON decodificado del error (shape completo del API).
 - `getRawBody()`: cuerpo crudo de la respuesta.
 
 ```php
 use Facturapi\Exceptions\FacturapiException;
+use Facturapi\RequestErrorCode;
 
 try {
   $facturapi->Invoices->create($payload);
 } catch (FacturapiException $e) {
   $status = $e->getStatusCode();
   $error = $e->getErrorData(); // Shape completo del error del API cuando el body es JSON válido.
-  $firstDetail = $error['details'][0] ?? null; // p.ej. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
+  $firstDetail = $error['errors'][0] ?? null; // p.ej. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
+  $retryAfter = $e->getApiErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
+    ? ($e->getResponseHeaders()['retry-after'] ?? null)
+    : null;
 }
 ```
 
diff --git a/README.md b/README.md
index c5ffd4f..3dd5bd0 100644
--- a/README.md
+++ b/README.md
@@ -175,18 +175,23 @@ On non-2xx responses, the SDK throws `Facturapi\Exceptions\FacturapiException`.
 The exception includes:
 - `getMessage()`: API error message when present.
 - `getStatusCode()`: HTTP status code.
+- `getApiErrorCode()`: documented V2 root error code when present.
 - `getErrorData()`: decoded JSON error payload (full API shape).
 - `getRawBody()`: raw response body string.
 
 ```php
 use Facturapi\Exceptions\FacturapiException;
+use Facturapi\RequestErrorCode;
 
 try {
   $facturapi->Invoices->create($payload);
 } catch (FacturapiException $e) {
   $status = $e->getStatusCode();
   $error = $e->getErrorData(); // Full API error shape when body is valid JSON.
-  $firstDetail = $error['details'][0] ?? null; // e.g. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
+  $firstDetail = $error['errors'][0] ?? null; // e.g. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
+  $retryAfter = $e->getApiErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
+    ? ($e->getResponseHeaders()['retry-after'] ?? null)
+    : null;
 }
 ```
 
diff --git a/VERSION.md b/VERSION.md
index ff3a77f..0516f07 100644
--- a/VERSION.md
+++ b/VERSION.md
@@ -1,4 +1,6 @@
-4.5.0
+4.6.0
 
 ## Added
+- Add grouped constants for documented API root error codes and Facturapi-owned validation detail codes.
+- Add `FacturapiException::getApiErrorCode()` for the string V2 root error code while preserving `getErrorCode()` compatibility.
 - Expose structured API error metadata on `FacturapiException`, including `code`, `path`, `location`, `errors`, `logId`, and response headers.
diff --git a/composer.json b/composer.json
index a34b01e..123c797 100644
--- a/composer.json
+++ b/composer.json
@@ -40,7 +40,10 @@
   "autoload": {
     "psr-4": {
       "Facturapi\\": "src/"
-    }
+    },
+    "files": [
+      "src/ErrorCodes.php"
+    ]
   },
   "minimum-stability": "stable"
 }
diff --git a/src/ErrorCodes.php b/src/ErrorCodes.php
new file mode 100644
index 0000000..9c8eaa1
--- /dev/null
+++ b/src/ErrorCodes.php
@@ -0,0 +1,279 @@
+<?php
+
+namespace Facturapi;
+
+// Documented API root error.code constants. External PAC and SAT codes belong
+// in errors[].code and are intentionally not included in this catalog.
+
+final class CommonErrorCode
+{
+    public const CONFLICT = 'conflict';
+    public const FORBIDDEN = 'forbidden';
+    public const INTERNAL_ERROR = 'internal_error';
+    public const NOT_FOUND = 'not_found';
+    public const UNAUTHORIZED = 'unauthorized';
+}
+
+final class AuthErrorCode
+{
+    public const API_KEY_INVALID = 'api_key_invalid';
+    public const API_KEY_NOT_ALLOWED = 'api_key_not_allowed';
+    public const FEATURE_NOT_AVAILABLE = 'feature_not_available';
+    public const LIVE_API_KEY_REQUIRED = 'live_api_key_required';
+    public const MCP_PERMISSION_DENIED = 'mcp_permission_denied';
+    public const MISSING_CREDENTIALS = 'missing_credentials';
+    public const ORGANIZATION_INCOMPLETE = 'organization_incomplete';
+    public const SUBSCRIPTION_REQUIRED = 'subscription_required';
+    public const SUBSCRIPTION_LIVE_ACCESS_REQUIRED = 'subscription_live_access_required';
+    public const USER_KEY_INVALID = 'user_key_invalid';
+    public const USER_SUSPENDED = 'user_suspended';
+}
+
+final class RequestErrorCode
+{
+    public const IDEMPOTENCY_KEY_IN_USE = 'idempotency_key_in_use';
+    public const RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded';
+    public const DATE_RANGE_TOO_LARGE = 'date_range_too_large';
+    public const IMAGE_FILE_REQUIRED = 'image_file_required';
+    public const INVALID_COUNTRY_CODE = 'invalid_country_code';
+    public const INVALID_DATE = 'invalid_date';
+    public const INVALID_DATE_RANGE = 'invalid_date_range';
+    public const INVALID_IMAGE_FILE = 'invalid_image_file';
+    public const INVALID_JSON = 'invalid_json';
+    public const INVALID_REQUEST = 'invalid_request';
+    public const INVALID_MULTIPART_FORM_DATA = 'invalid_multipart_form_data';
+    public const INVALID_STATE_CODE = 'invalid_state_code';
+    public const INVALID_TIMEZONE = 'invalid_timezone';
+    public const MULTIPART_LIMIT_EXCEEDED = 'multipart_limit_exceeded';
+    public const PAGE_TOO_LARGE = 'page_too_large';
+    public const PAYLOAD_TOO_LARGE = 'payload_too_large';
+}
+
+final class CustomerErrorCode
+{
+    public const CUSTOMER_COULD_NOT_BE_RESOLVED = 'customer_could_not_be_resolved';
+    public const CUSTOMER_EDIT_LINK_NOT_FOUND = 'customer_edit_link_not_found';
+    public const CUSTOMER_EDIT_LINK_UNAVAILABLE = 'customer_edit_link_unavailable';
+    public const CUSTOMER_EMAIL_REQUIRED = 'customer_email_required';
+    public const CUSTOMER_HAS_INVOICES = 'customer_has_invoices';
+    public const CUSTOMER_NOT_FOUND = 'customer_not_found';
+    public const CUSTOMER_TAX_INFO_UNAVAILABLE = 'customer_tax_info_unavailable';
+}
+
+final class TaxInfoValidationCode
+{
+    public const LEGAL_NAME_MISMATCH = 'legal_name_mismatch';
+    public const TAX_ADDRESS_ZIP_MISMATCH = 'tax_address_zip_mismatch';
+    public const TAX_ID_NOT_FOUND = 'tax_id_not_found';
+    public const TAX_SYSTEM_NOT_ALLOWED_FOR_TAX_ID = 'tax_system_not_allowed_for_tax_id';
+    public const TAX_SYSTEM_NOT_IN_CATALOG = 'tax_system_not_in_catalog';
+}
+
+final class ProductErrorCode
+{
+    public const PRODUCT_NOT_FOUND = 'product_not_found';
+}
+
+final class SupplierErrorCode
+{
+    public const SUPPLIER_NOT_FOUND = 'supplier_not_found';
+}
+
+final class CatalogErrorCode
+{
+    public const PRODUCT_KEY_NOT_FOUND = 'product_key_not_found';
+    public const TARIFF_CODE_NOT_FOUND = 'tariff_code_not_found';
+    public const UNIT_KEY_NOT_FOUND = 'unit_key_not_found';
+}
+
+final class InvoiceErrorCode
+{
+    public const INVOICE_ALREADY_STAMPED = 'invoice_already_stamped';
+    public const INVOICE_NOT_DRAFT = 'invoice_not_draft';
+    public const INVOICE_NOT_FOUND = 'invoice_not_found';
+    public const INVOICE_NOT_STAMPED = 'invoice_not_stamped';
+}
+
+final class InvoiceDraftErrorCode
+{
+    public const DRAFT_NOT_READY_TO_STAMP = 'draft_not_ready_to_stamp';
+    public const DRAFT_UPDATE_IN_PROGRESS = 'draft_update_in_progress';
+}
+
+final class InvoiceStampingErrorCode
+{
+    public const INVOICE_STAMPING_FAILED = 'invoice_stamping_failed';
+    public const INVOICE_STAMPING_SERVICE_UNAVAILABLE = 'invoice_stamping_service_unavailable';
+    public const INVOICE_STAMPING_VALIDATION_ERROR = 'invoice_stamping_validation_error';
+    public const MANIFESTO_SIGNATURE_FAILED = 'manifesto_signature_failed';
+    public const STAMPING_IN_PROGRESS = 'stamping_in_progress';
+}
+
+final class InvoiceDeliveryErrorCode
+{
+    public const INVOICE_EMAIL_DELIVERY_FAILED = 'invoice_email_delivery_failed';
+    public const INVOICE_EMAIL_RECIPIENT_REQUIRED = 'invoice_email_recipient_required';
+    public const INVOICE_EMAIL_STATUS_NOT_ALLOWED = 'invoice_email_status_not_allowed';
+}
+
+final class InvoiceCancellationErrorCode
+{
+    public const INVOICE_CANCELLATION_IN_PROGRESS = 'invoice_cancellation_in_progress';
+    public const INVOICE_CANCELLATION_RECEIPT_UNAVAILABLE = 'invoice_cancellation_receipt_unavailable';
+    public const INVOICE_CANCELLATION_FAILED = 'invoice_cancellation_failed';
+    public const INVOICE_CANCELLATION_NOT_ALLOWED = 'invoice_cancellation_not_allowed';
+    public const INVOICE_CANCELLATION_NOT_FOUND = 'invoice_cancellation_not_found';
+    public const INVOICE_CANCELLATION_RFC_MISMATCH = 'invoice_cancellation_rfc_mismatch';
+    public const INVOICE_CANCELLATION_SERVICE_UNAVAILABLE = 'invoice_cancellation_service_unavailable';
+    public const INVOICE_NOT_CANCELABLE = 'invoice_not_cancelable';
+    public const INVOICE_NOT_CANCELABLE_BY_SAT = 'invoice_not_cancelable_by_sat';
+    public const SUBSTITUTION_INVOICE_CANCELED = 'substitution_invoice_canceled';
+    public const SUBSTITUTION_INVOICE_NOT_FOUND = 'substitution_invoice_not_found';
+    public const SUBSTITUTION_INVOICE_REQUIRED = 'substitution_invoice_required';
+    public const SUBSTITUTION_INVOICE_STATUS_NOT_ALLOWED = 'substitution_invoice_status_not_allowed';
+}
+
+final class ReceiptErrorCode
+{
+    public const RECEIPT_EXPIRED = 'receipt_expired';
+    public const RECEIPT_NOT_FOUND = 'receipt_not_found';
+    public const RECEIPT_NOT_OPEN = 'receipt_not_open';
+}
+
+final class ReceiptInvoicingErrorCode
+{
+    public const RECEIPT_INVOICING_ADDRESS_MISMATCH = 'receipt_invoicing_address_mismatch';
+    public const RECEIPT_INVOICING_CUSTOMER_MISMATCH = 'receipt_invoicing_customer_mismatch';
+    public const RECEIPT_INVOICING_TOO_MANY_ITEMS = 'receipt_invoicing_too_many_items';
+    public const RECEIPT_KEYS_NOT_FOUND = 'receipt_keys_not_found';
+}
+
+final class ReceiptGlobalInvoiceErrorCode
+{
+    public const GLOBAL_INVOICE_TOO_MANY_ITEMS = 'global_invoice_too_many_items';
+    public const INVALID_GLOBAL_INVOICE_PERIOD = 'invalid_global_invoice_period';
+}
+
+final class RetentionErrorCode
+{
+    public const INVALID_RETENTION_COMPLEMENT = 'invalid_retention_complement';
+    public const RETENTION_NOT_FOUND = 'retention_not_found';
+    public const RETENTION_NOT_STAMPED = 'retention_not_stamped';
+    public const RETENTION_NOT_CANCELABLE = 'retention_not_cancelable';
+}
+
+final class RetentionDeliveryErrorCode
+{
+    public const RETENTION_EMAIL_DELIVERY_FAILED = 'retention_email_delivery_failed';
+    public const RETENTION_EMAIL_RECIPIENT_REQUIRED = 'retention_email_recipient_required';
+    public const RETENTION_EMAIL_STATUS_NOT_ALLOWED = 'retention_email_status_not_allowed';
+}
+
+final class RetentionCancellationErrorCode
+{
+    public const RETENTION_CANCELLATION_FAILED = 'retention_cancellation_failed';
+    public const RETENTION_CANCELLATION_SERVICE_UNAVAILABLE = 'retention_cancellation_service_unavailable';
+}
+
+final class RetentionStampingErrorCode
+{
+    public const RETENTION_STAMPING_FAILED = 'retention_stamping_failed';
+    public const RETENTION_STAMPING_SERVICE_UNAVAILABLE = 'retention_stamping_service_unavailable';
+    public const RETENTION_STAMPING_VALIDATION_ERROR = 'retention_stamping_validation_error';
+}
+
+final class OrganizationErrorCode
+{
+    public const INVALID_OPERATION = 'invalid_operation';
+    public const INVALID_USER_ID = 'invalid_user_id';
+    public const ORGANIZATION_NOT_FOUND = 'organization_not_found';
+    public const SUBSCRIPTION_ACTIVE_REQUIRED = 'subscription_active_required';
+}
+
+final class OrganizationSettingsErrorCode
+{
+    public const CERTIFICATE_EXPIRED = 'certificate_expired';
+    public const CERTIFICATE_FILE_REQUIRED = 'certificate_file_required';
+    public const CERTIFICATE_FILES_INVALID = 'certificate_files_invalid';
+    public const CERTIFICATE_FILES_REQUIRED = 'certificate_files_required';
+    public const CERTIFICATE_FIEL_RFC_MISMATCH = 'certificate_fiel_rfc_mismatch';
+    public const CERTIFICATE_INVALID = 'certificate_invalid';
+    public const CERTIFICATE_NOT_YET_VALID = 'certificate_not_yet_valid';
+    public const CERTIFICATE_PREVIOUS_RFC_MISMATCH = 'certificate_previous_rfc_mismatch';
+    public const CSD_REQUIRED = 'csd_required';
+    public const FIEL_INVALID = 'fiel_invalid';
+    public const FIEL_RFC_MISMATCH = 'fiel_rfc_mismatch';
+    public const FIEL_REQUIRED = 'fiel_required';
+    public const ORGANIZATION_DOMAIN_CHANGE_NOT_ALLOWED = 'organization_domain_change_not_allowed';
+    public const ORGANIZATION_DOMAIN_UNAVAILABLE = 'organization_domain_unavailable';
+    public const ORGANIZATION_SETTINGS_INVALID = 'organization_settings_invalid';
+    public const ORGANIZATION_SUPPORT_EMAIL_REQUIRED = 'organization_support_email_required';
+    public const ORGANIZATION_TAX_INFO_INVALID = 'organization_tax_info_invalid';
+    public const PRIVATE_KEY_CERTIFICATE_MISMATCH = 'private_key_certificate_mismatch';
+    public const PRIVATE_KEY_FILE_REQUIRED = 'private_key_file_required';
+    public const PRIVATE_KEY_PASSWORD_INCORRECT = 'private_key_password_incorrect';
+}
+
+final class OrganizationInviteErrorCode
+{
+    public const INVITE_EMAIL_DELIVERY_FAILED = 'invite_email_delivery_failed';
+    public const INVITE_EMAIL_MISMATCH = 'invite_email_mismatch';
+    public const INVITE_EXPIRED = 'invite_expired';
+    public const INVITE_NOT_FOUND = 'invite_not_found';
+    public const INVITE_ROLE_UNAVAILABLE = 'invite_role_unavailable';
+    public const USER_ALREADY_IN_ORGANIZATION = 'user_already_in_organization';
+}
+
+final class OrganizationAccessErrorCode
+{
+    public const ORGANIZATION_ADMIN_ACCESS_CANNOT_BE_REMOVED = 'organization_admin_access_cannot_be_removed';
+    public const ORGANIZATION_ADMIN_ASSIGNMENT_CANNOT_BE_EDITED = 'organization_admin_assignment_cannot_be_edited';
+    public const ORGANIZATION_ADMIN_ROLE_CANNOT_BE_DELETED = 'organization_admin_role_cannot_be_deleted';
+    public const ORGANIZATION_ADMIN_ROLE_CANNOT_BE_EDITED = 'organization_admin_role_cannot_be_edited';
+    public const ORGANIZATION_ADMIN_ROLE_REQUIRED = 'organization_admin_role_required';
+    public const ORGANIZATION_ID_NOT_ALLOWED = 'organization_id_not_allowed';
+    public const ORGANIZATION_ID_REQUIRED = 'organization_id_required';
+    public const OWNER_ACCESS_CANNOT_BE_REASSIGNED = 'owner_access_cannot_be_reassigned';
+    public const OWNER_ACCESS_CANNOT_BE_REMOVED = 'owner_access_cannot_be_removed';
+    public const ROLE_HAS_ASSIGNED_USERS = 'role_has_assigned_users';
+    public const ROLE_TEMPLATE_NOT_FOUND = 'role_template_not_found';
+    public const ROLE_NOT_FOUND = 'role_not_found';
+    public const USER_ACCESS_NOT_FOUND = 'user_access_not_found';
+}
+
+final class OrganizationSeriesErrorCode
+{
+    public const SERIES_ALREADY_EXISTS = 'series_already_exists';
+    public const SERIES_NOT_FOUND = 'series_not_found';
+}
+
+final class WebhookErrorCode
+{
+    public const WEBHOOK_DELIVERY_ATTEMPT_NOT_FOUND = 'webhook_delivery_attempt_not_found';
+    public const WEBHOOK_NOT_FOUND = 'webhook_not_found';
+    public const WEBHOOK_SIGNATURE_INVALID = 'webhook_signature_invalid';
+}
+
+final class ToolErrorCode
+{
+    public const TAX_ID_VALIDATION_FAILED = 'tax_id_validation_failed';
+    public const TAX_ID_VALIDATION_SERVICE_UNAVAILABLE = 'tax_id_validation_service_unavailable';
+}
+
+final class ValidationErrorCode
+{
+    public const AMOUNT_EXCEEDS_RELATED_DOCUMENT_BALANCE = 'amount_exceeds_related_document_balance';
+    public const EXCHANGE_RATE_TOO_LARGE = 'exchange_rate_too_large';
+    public const EXCHANGE_RATE_TOO_SMALL = 'exchange_rate_too_small';
+    public const INVALID_FORMAT = 'invalid_format';
+    public const INVALID_LENGTH = 'invalid_length';
+    public const INVALID_TYPE = 'invalid_type';
+    public const NOT_FOUND = 'not_found';
+    public const NOT_ALLOWED = 'not_allowed';
+    public const REQUIRED = 'required';
+    public const TOO_LARGE = 'too_large';
+    public const TOO_SMALL = 'too_small';
+    public const UNKNOWN_FIELD = 'unknown_field';
+    public const INVALID_VALUE = 'invalid_value';
+}
+
diff --git a/src/Exceptions/FacturapiException.php b/src/Exceptions/FacturapiException.php
index 958dadd..7c56081 100644
--- a/src/Exceptions/FacturapiException.php
+++ b/src/Exceptions/FacturapiException.php
@@ -53,6 +53,17 @@ public function getErrorCode(): mixed
 		return is_array($this->errorData) ? ($this->errorData['code'] ?? null) : null;
 	}
 
+	/**
+	 * Returns the documented V2 API root error code when the response contains one.
+	 * getErrorCode() remains available for compatibility with older API responses.
+	 */
+	public function getApiErrorCode(): ?string
+	{
+		return is_array($this->errorData) && is_string($this->errorData['code'] ?? null)
+			? $this->errorData['code']
+			: null;
+	}
+
 	public function getErrorPath(): ?string
 	{
 		return is_array($this->errorData) && is_string($this->errorData['path'] ?? null)
diff --git a/src/Facturapi.php b/src/Facturapi.php
index b235f03..da26dfa 100644
--- a/src/Facturapi.php
+++ b/src/Facturapi.php
@@ -6,6 +6,7 @@
 // Composer/PSR-4 users can continue relying on autoloading.
 require_once __DIR__ . '/Http/BaseClient.php';
 require_once __DIR__ . '/Exceptions/FacturapiException.php';
+require_once __DIR__ . '/ErrorCodes.php';
 require_once __DIR__ . '/Exceptions/Facturapi_Exception.php';
 require_once __DIR__ . '/InvoiceRelation.php';
 require_once __DIR__ . '/InvoiceType.php';
diff --git a/tests/Http/ErrorHandlingTest.php b/tests/Http/ErrorHandlingTest.php
index d22e7d2..250090b 100644
--- a/tests/Http/ErrorHandlingTest.php
+++ b/tests/Http/ErrorHandlingTest.php
@@ -5,6 +5,7 @@
 namespace Facturapi\Tests\Http;
 
 use Facturapi\Exceptions\FacturapiException;
+use Facturapi\RequestErrorCode;
 use Facturapi\Resources\Invoices;
 use Facturapi\Tests\Support\FakeHttpClient;
 use GuzzleHttp\Psr7\Response;
@@ -16,16 +17,9 @@ public function testApiErrorShapeIsFullyAvailableOnException(): void
     {
         $errorBody = [
             'message' => 'Request validation failed',
-            'code' => 'validation_error',
+            'code' => 'invalid_request',
             'path' => 'customer.tax_id',
             'location' => 'body',
-            'details' => [
-                [
-                    'path' => 'customer.tax_id',
-                    'message' => 'customer.tax_id must be a valid RFC',
-                    'code' => 'invalid_rfc',
-                ],
-            ],
             'errors' => [
                 [
                     'path' => 'customer.tax_id',
@@ -56,16 +50,15 @@ public function testApiErrorShapeIsFullyAvailableOnException(): void
             self::assertSame($errorBody, $exception->getResponseData());
             self::assertSame(json_encode($errorBody), $exception->getRawBody());
 
-            self::assertSame('validation_error', $exception->getErrorData()['code']);
-            self::assertSame('validation_error', $exception->getErrorCode());
+            self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getErrorData()['code']);
+            self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getErrorCode());
+            self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getApiErrorCode());
             self::assertSame('customer.tax_id', $exception->getErrorPath());
             self::assertSame('body', $exception->getErrorLocation());
             self::assertSame($errorBody['errors'], $exception->getErrors());
             self::assertSame('log_123', $exception->getLogId());
             self::assertSame('3', $exception->getResponseHeaders()['retry-after']);
             self::assertSame('log_123', $exception->getResponseHeaders()['x-facturapi-log-id']);
-            self::assertSame('customer.tax_id', $exception->getErrorData()['details'][0]['path']);
-            self::assertSame('invalid_rfc', $exception->getErrorData()['details'][0]['code']);
         }
     }
 

From 511c66693bc94011546763c9a3db949732dd6f86 Mon Sep 17 00:00:00 2001
From: javorosas <javier.rosasb@gmail.com>
Date: Thu, 16 Jul 2026 20:09:27 +0200
Subject: [PATCH 2/2] fix: return API error codes as strings

---
 README.es.md                          |  4 ++--
 README.md                             |  4 ++--
 VERSION.md                            |  2 +-
 src/Exceptions/FacturapiException.php | 11 +----------
 tests/Http/ErrorHandlingTest.php      |  8 +++++++-
 5 files changed, 13 insertions(+), 16 deletions(-)

diff --git a/README.es.md b/README.es.md
index 5d346e9..66f0b11 100644
--- a/README.es.md
+++ b/README.es.md
@@ -175,7 +175,7 @@ En respuestas no-2xx, el SDK lanza `Facturapi\Exceptions\FacturapiException`.
 La excepción incluye:
 - `getMessage()`: mensaje del API cuando está disponible.
 - `getStatusCode()`: código HTTP.
-- `getApiErrorCode()`: código raíz documentado de V2 cuando está disponible.
+- `getErrorCode()`: código raíz documentado de V2 cuando está disponible.
 - `getErrorData()`: payload JSON decodificado del error (shape completo del API).
 - `getRawBody()`: cuerpo crudo de la respuesta.
 
@@ -189,7 +189,7 @@ try {
   $status = $e->getStatusCode();
   $error = $e->getErrorData(); // Shape completo del error del API cuando el body es JSON válido.
   $firstDetail = $error['errors'][0] ?? null; // p.ej. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
-  $retryAfter = $e->getApiErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
+  $retryAfter = $e->getErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
     ? ($e->getResponseHeaders()['retry-after'] ?? null)
     : null;
 }
diff --git a/README.md b/README.md
index 3dd5bd0..7aec1aa 100644
--- a/README.md
+++ b/README.md
@@ -175,7 +175,7 @@ On non-2xx responses, the SDK throws `Facturapi\Exceptions\FacturapiException`.
 The exception includes:
 - `getMessage()`: API error message when present.
 - `getStatusCode()`: HTTP status code.
-- `getApiErrorCode()`: documented V2 root error code when present.
+- `getErrorCode()`: documented V2 root error code when present.
 - `getErrorData()`: decoded JSON error payload (full API shape).
 - `getRawBody()`: raw response body string.
 
@@ -189,7 +189,7 @@ try {
   $status = $e->getStatusCode();
   $error = $e->getErrorData(); // Full API error shape when body is valid JSON.
   $firstDetail = $error['errors'][0] ?? null; // e.g. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
-  $retryAfter = $e->getApiErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
+  $retryAfter = $e->getErrorCode() === RequestErrorCode::RATE_LIMIT_EXCEEDED
     ? ($e->getResponseHeaders()['retry-after'] ?? null)
     : null;
 }
diff --git a/VERSION.md b/VERSION.md
index 0516f07..5ffcdcb 100644
--- a/VERSION.md
+++ b/VERSION.md
@@ -2,5 +2,5 @@
 
 ## Added
 - Add grouped constants for documented API root error codes and Facturapi-owned validation detail codes.
-- Add `FacturapiException::getApiErrorCode()` for the string V2 root error code while preserving `getErrorCode()` compatibility.
+- Fix `FacturapiException::getErrorCode()` to return only documented string API root codes.
 - Expose structured API error metadata on `FacturapiException`, including `code`, `path`, `location`, `errors`, `logId`, and response headers.
diff --git a/src/Exceptions/FacturapiException.php b/src/Exceptions/FacturapiException.php
index 7c56081..2bfb798 100644
--- a/src/Exceptions/FacturapiException.php
+++ b/src/Exceptions/FacturapiException.php
@@ -48,16 +48,7 @@ public function getRawBody(): ?string
 		return $this->rawBody;
 	}
 
-	public function getErrorCode(): mixed
-	{
-		return is_array($this->errorData) ? ($this->errorData['code'] ?? null) : null;
-	}
-
-	/**
-	 * Returns the documented V2 API root error code when the response contains one.
-	 * getErrorCode() remains available for compatibility with older API responses.
-	 */
-	public function getApiErrorCode(): ?string
+	public function getErrorCode(): ?string
 	{
 		return is_array($this->errorData) && is_string($this->errorData['code'] ?? null)
 			? $this->errorData['code']
diff --git a/tests/Http/ErrorHandlingTest.php b/tests/Http/ErrorHandlingTest.php
index 250090b..2efaee8 100644
--- a/tests/Http/ErrorHandlingTest.php
+++ b/tests/Http/ErrorHandlingTest.php
@@ -52,7 +52,6 @@ public function testApiErrorShapeIsFullyAvailableOnException(): void
 
             self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getErrorData()['code']);
             self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getErrorCode());
-            self::assertSame(RequestErrorCode::INVALID_REQUEST, $exception->getApiErrorCode());
             self::assertSame('customer.tax_id', $exception->getErrorPath());
             self::assertSame('body', $exception->getErrorLocation());
             self::assertSame($errorBody['errors'], $exception->getErrors());
@@ -82,4 +81,11 @@ public function testNonJsonErrorsStillExposeRawBody(): void
             self::assertSame($rawBody, $exception->getRawBody());
         }
     }
+
+    public function testNumericRootErrorCodeIsIgnored(): void
+    {
+        $exception = new FacturapiException(errorData: ['code' => 400]);
+
+        self::assertNull($exception->getErrorCode());
+    }
 }