API Reference

Error codes

Every error returned by the Aethar API suite, documented with a stable URL. Deep-link any code from logs, Sentry, or your agent runtime straight to this reference. Each page includes an example payload and recovery steps.

31
Codes
11
Categories
9
HTTP statuses

Authentication

04 codes
401MISSING_API_KEYAPI key is missing. The X-API-Key header is required on every request.401INVALID_API_KEYAPI key is invalid or malformed. Check for typos — keys have prefixes like wa_, cl_, sk_, ei_, eu_.401DEACTIVATED_KEYAPI key has been deactivated. Generate a new key in console.aethar.dev.401EXPIRED_KEYAPI key has expired. Generate a new key to continue.

Authorization

01 code
403SCOPE_DENIEDYour API key lacks permission for this endpoint. Compliance endpoints require Growth tier or higher.

Rate limiting

01 code
429RATE_LIMIT_EXCEEDEDDaily request limit exceeded. Free tier is 100 req/day, resets at midnight UTC.

Infrastructure

02 codes
503SERVICE_UNAVAILABLEService is temporarily unavailable. Retry with exponential backoff.500INTERNAL_ERRORUnexpected server error. This shouldn't happen — please report it.

Validation

01 code
422VALIDATION_ERRORRequest parameters failed validation. Response body includes an `errors` array with per-field detail.

Salary (WageAPI)

03 codes
400LOCATION_NOT_FOUNDLocation could not be resolved. Use a BLS metro area (e.g. 'Austin, TX'), EU country name, or ISO code.404NO_SALARY_DATANo salary data available for the requested job/location combination.404NO_BENCHMARK_DATANo salary benchmark for this job/country combination yet.

Compliance (WageAPI)

06 codes
200DIRECTIVE_NOT_TRANSPOSEDWarning: Country has not yet transposed EU Directive 2023/970 on pay transparency — response uses directive defaults.400RANGE_MISSINGInvalid salary range. `min_salary` must be positive and less than `max_salary`.400BELOW_MINIMUM_WAGEMinimum salary is below the national minimum wage for this country.400BELOW_MARKETEntire salary range is below the 25th percentile benchmark.400ABOVE_MARKETEntire salary range is above the 75th percentile benchmark.400RANGE_TOO_WIDESalary range exceeds 100% of the benchmark mean. Narrow it for a realistic posting.

Cost of Living (CostAPI)

02 codes
404COUNTRY_NOT_FOUNDNo data for the specified country. Use ISO 3166-1 alpha-2 code or English country name.404NO_CPI_DATANo CPI data available for the requested country. Check supported countries list.

Skills (SkillsAPI)

02 codes
404OCCUPATION_NOT_FOUNDOccupation SOC code not found in the taxonomy.404SKILL_NOT_FOUNDSkill ID not found.

E-Invoicing (EInvoiceAPI)

07 codes
400UNSUPPORTED_FORMATInvoice format not supported.400CONVERSION_FAILEDInvoice conversion failed. Source document likely missing EN 16931 required fields.400SCHEMATRON_FAILEDInvoice failed regulatory validation (Schematron rules). Response includes the failing rule.400UNANONYMIZED_PII_DETECTEDResidual PII detected after anonymization step. Manually redact before submitting.500ANONYMIZATION_INTEGRITY_ERRORAI output failed deanonymization integrity check. Retry the request.503AI_SERVICE_ERRORAI service unavailable. Retry after a few seconds.404NOT_FOUNDDocument not found or expired. Converted documents have a 24-hour TTL.

Eurostat (EurostatAPI)

02 codes
404DATASET_NOT_FOUNDDataset code not found in Eurostat.404NO_GDP_DATANo GDP data for the requested country. EurostatAPI covers EU/EEA members only.