Договор за отговори и грешки на Admin API

Този файл допълва договора за отговори за всяка крайна точка в Справочник за крайни точки. Прочетете реда на крайната точка за успешното тяло и таблиците по-долу за всички общи или специфични неуспешни тела. По подразбиране грешките използват няколко съвместими структури; клиентите могат да изберат една универсална обвивка.

Незадължителна структурирана обвивка за грешки

Изпратете тази заглавка на заявката към която и да е крайна точка:

X-Error-Format: envelope

Стойността се сравнява след премахване на крайните интервали, без значение на регистъра. При точно тази стойност всеки JSON отговор със състояние 400 или по-високо се преобразува в:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Примерно преобразуване на стандартно тяло за валидация:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Правилата за преобразуване са точни:

• validationErrors става details.fields, а code става VALIDATION_FAILED, дори когато стандартното тяло има и домейн код.
• При липса на полета за валидация се запазва code по подразбиране на най-горно ниво.
• Другите свойства на най-горно ниво, освен error, message, validationErrors и code, се преместват в details; например limit при експорт на отчет става details.limit.
• Текстово error на най-горно ниво става message. Ако липсва, се използва резервната стойност за състоянието.
• Резервните кодове са AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 и други некласифицирани 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) и INTERNAL_ERROR (други 5xx, включително 503).
• requestId е точната заглавка X-Request-Id на отговора. Подаден от клиента ID на заявка се използва само ако след премахване на крайните интервали съответства на [A-Za-z0-9._:-]{1,128}; иначе сървърът генерира UUID.

Преобразуването не променя състоянието или заглавките, несвързани с тялото. То важи и за идемпотентни повторения според заглавката X-Error-Format на повторената заявка. Двоичните успешни отговори остават двоични; JSON грешките им се обвиват. Останалите таблици показват стандартните тела; правилата по-горе дават другото възможно тяло за всеки ред.

Нотация на отговорите

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

error и текстът на съобщението за валидация са описателни, а не стабилен програмен разграничител. Разграничавайте по code, когато присъства. Валидацията на заявката връща 422 ValidationError; валидацията на цял обект може да даде { "validationErrors": {} }, когато не е посочено отделно поле. Невалиден JSON и неочаквани грешки връщат глобалното 500 PlainError, показано по-долу.

Всички JSON примери показват точната структура на тялото. Текстът <message> е върнатото съобщение за валидация или операция и представлява JSON низ, а не буквална стойност в ъглови скоби.

Ред на обработка на заявки

Заявките се обработват в този ред:

1. конфигурация и удостоверяване с токен на работно пространство;
2. политика на хоста и лимити на заявки за токен/работно пространство;
3. филтриране по текущи права;
4. за всяка промяна — валидация/заявяване на идемпотентност;
5. проверки на обхвата на крайната точка, валидация на заявката и заявената операция.

Следователно промяна с валиден токен, но недостатъчен обхват, все пак трябва да изпрати Idempotency-Key. Завършен отговор за промяна 403, 404, 409 или 422 може да бъде повторен със същия ключ/заявка.

Отговори за удостоверяване, политики и ограничаване на заявки

Тези отговори могат да възникнат на всяка регистрирана крайна точка /v2/admin преди специфичната ѝ обработка.

API достъпът е включен във всеки план. Изключването на adminApiEnabled за хоста на работното пространство връща 404; загубата на допълнително право за функция премахва само засегнатите обхвати. Полученият отказ за обхват използва отговора по-долу, а не процес за обновяване на токен.

Обхват, идемпотентност, парсване, собственост и неочаквани грешки

ID на ресурсите в пътя трябва да са положителни числа. Неположително или нечислово :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId или :localUserId връща 422 ValidationError, а не 400.

Грешки на обекти и управление на мощността

Грешки на станции

mapChargerErrors() се използва за създаване/актуализация на станция, данни за достъп, настройки на конектор, публично показване, разрешаване на QR съдържание, промяна/презареждане на конфигурация, стартиране на фърмуер, всичките четири основни команди и заявка за съставен график.

Обикновените операции за четене връщат само общите отговори 401/403/404/429/500/503 и валидация 422 на заявката/пътя. Изтриването на станция може да върне общото 500 PlainError, ако е неуспешно без по-конкретен отговор за грешка.

Грешки на отчети

Успешният експорт е двоичен; всички грешки при експорт остават JSON.

Грешки на тарифи

Грешки на профили за зареждане

Грешки в потребителския домейн

Грешките при валидация на потребител, посочващи поле, използват ValidationError и code; останалите потребителски грешки използват CodedError. Всички случаи на липсващ ресурс използват общия отговор RESOURCE_NOT_FOUND, който не разкрива съществуването на ресурси.

POST /users/invitations може да върне и общото 403 INSUFFICIENT_SCOPE след парсване на тялото, ако липсва users:access, или ако е подаден RFID и липсва users:rfid. Крайните точки за локални потребители изброяват всеки задължителен обхват в Справочник за крайни точки.

Кодовете за потребителски грешки се прилагат така:

Всички резултати за собственост и липсващи ресурси в тези групи, включително нерегистриран имейл при POST /users, използват общото тяло 404 RESOURCE_NOT_FOUND.

Отговори без тяло и при повторение

Успешният отговор 204 няма тяло. Това важи за всяко документирано изтриване с 204 empty. Завършено идемпотентно повторение задава Idempotency-Replayed: true и използва запазените състояние/тяло; за 204 HTTP отговорът остава без тяло. API никога не връща успешен JSON обект за документирана операция 204.