Pamācības

Kļūdas

Kļūdas tiek atgrieztas standarta problem details formātā ar satura tipu application/problem+json. Vispirms pārbaudiet HTTP statusu; lietojiet type, lai atšķirtu cēloņus.

Piezīme

Paskaidrojošie teksti kļūdu atbildēs (detail, message) ir angļu valodā un var tikt pārfrāzēti. Balstiet savu kodu uz status un type, nevis uz teksta.

#Formāts

Validācijas kļūda

Validācija ziņo par visām problēmām uzreiz, lai jūs varētu tās labot vienā reizē.

curl -X POST "$API/v1/locations" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "",
  "latitude": 95,
  "longitude": 24.0536
}'

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/locations`, {
  method: "POST",
  headers: { Authorization: auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "",
    "latitude": 95,
    "longitude": 24.0536
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/locations",
    auth=(CLIENT_ID, CLIENT_SECRET),
    json={
        "name": "",
        "latitude": 95,
        "longitude": 24.0536,
    },
)
print(r.status_code, r.json())

422 Unprocessable Content

{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "5f22a099-b84d-48eb-b078-6c5423a2175e",
  "errors": [
    {
      "field": "name",
      "message": "must not be empty"
    },
    {
      "field": "latitude",
      "message": "Number must be less than or equal to 90"
    }
  ]
}

Lauks	Nozīme
`type`	Stabils problēmas veida identifikators (skatiet tabulu zemāk). Salīdziniet pēc tā, nevis pēc teksta.
`title, detail`	Īss, cilvēkam lasāms skaidrojums. Formulējums laika gaitā var uzlaboties.
`status`	HTTP statuss, atkārtots.
`request_id`	Šī pieprasījuma unikāls identifikators, arī galvenē `X-Request-Id`. Norādiet to, sazinoties ar atbalstu.
`errors`	Tikai `422`: saraksts ar `{ field, message }`, viens katrai problēmai.

#Problēmu veidi

Katrs type sākas ar https://api.boxlatvia.lv/problems/. Tie ir identifikatori, nevis tīmekļa lapas.

Veids	Statuss	Nozīme
`bad-request`	400	Saturs nav derīgs JSON, vai parametrs, piemēram, `cursor`, nav nolasāms.
`unauthorized`	401	Trūkstoši, nepareizi, beigušies vai atsaukti piekļuves dati, vai beidzies tokens.
`forbidden`	403	IP adrese šiem piekļuves datiem nav atļauta, vai darbība piegādātājiem nav pieejama.
`insufficient-scope`	403	Piekļuves datiem trūkst izsaukumam vajadzīgo tiesību; `required_scope` tās nosauc.
`not-found`	404	Jums nav šāda objekta. Citu piegādātāju objekti izskatās tieši tāpat.
`conflict / duplicate-external-id`	409	`external_id` ir aizņemts (`existing_id` nosauc otru objektu).
`location-has-boxes`	409	Lokācijā vēl ir telpas.
`box-has-orders`	409	Telpai ir pasūtījumi, un to nevar dzēst.
`box-already-published`	409	Publicētu telpu nevar iesniegt; vispirms atsauciet to.
`image-limit`	409	Vairāk nekā 20 attēli; `limit` un `existing` norāda skaitļus.
`request-in-progress`	409	Jūsu iepriekšējais izsaukums ar to pašu `Idempotency-Key` vēl darbojas.
`precondition-failed`	412	`If-Match` ir novecojis: nolasiet objektu vēlreiz.
`payload-too-large`	413	Pieprasījums ir lielāks par 27 MB.
`unsupported-media-type`	415	Attēli jāsūta kā `multipart/form-data`.
`validation-failed`	422	Kāda vērtība ir nederīga; `errors` uzskaita visas problēmas.
`box-incomplete`	422	Telpu vēl nevar iesniegt; `missing` uzskaita, kas tai vajadzīgs.
`idempotency-key-reused`	422	Šī `Idempotency-Key` jau tika izmantota citam pieprasījumam.
`precondition-required`	428	Trūkst `If-Match`.
`too-many-requests`	429	Pārāk daudz neveiksmīgu autentifikāciju no jūsu adreses; uzgaidiet `Retry-After` sekundes.
`internal-error / timeout / storage-unavailable`	500	Kaut kas nogāja greizi mūsu pusē (`timeout` ir 503, `storage-unavailable` ir 502). Mēģiniet atkārtoti ar to pašu `Idempotency-Key`.

#Piemēri

Nepareizi vai trūkstoši piekļuves dati

curl "$API/v1/me"

const API = "https://api.boxlatvia.lv";

const res = await fetch(`${API}/v1/me`);
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.get(
    f"{API}/v1/me",
)
print(r.status_code, r.json())

401 UnauthorizedWww-Authenticate: Basic realm="BoxLatvia Supplier API", Bearer realm="BoxLatvia Supplier API"

{
  "type": "https://api.boxlatvia.lv/problems/unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "Send HTTP Basic credentials or a Bearer token.",
  "request_id": "3f502d49-40f5-43e8-8004-dc4bb2f28a99"
}

Objekts nav atrasts

curl "$API/v1/boxes/e8e189c3-3ac4-47d0-8ff1-584221c4e1ae" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/boxes/e8e189c3-3ac4-47d0-8ff1-584221c4e1ae`, {
  headers: { Authorization: auth },
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.get(
    f"{API}/v1/boxes/e8e189c3-3ac4-47d0-8ff1-584221c4e1ae",
    auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())

404 Not Found

{
  "type": "https://api.boxlatvia.lv/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such box.",
  "request_id": "734e0d86-9a60-4107-9997-c9f0bcf77610"
}

Telpa, kas vēl nav gatava

curl -X POST "$API/v1/boxes/9d7f53d3-a9cd-4ee1-b9cf-470a572f8b4e/submit" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/boxes/9d7f53d3-a9cd-4ee1-b9cf-470a572f8b4e/submit`, {
  method: "POST",
  headers: { Authorization: auth },
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/boxes/9d7f53d3-a9cd-4ee1-b9cf-470a572f8b4e/submit",
    auth=(CLIENT_ID, CLIENT_SECRET),
)
print(r.status_code, r.json())

422 Unprocessable Content

{
  "type": "https://api.boxlatvia.lv/problems/box-incomplete",
  "title": "Box is incomplete",
  "status": 422,
  "detail": "Fill in description, price, price_unit, size, features before submitting this box for review.",
  "request_id": "f48c9ebd-fa4f-4b14-be21-b98154de2c1e",
  "missing": [
    "description",
    "price",
    "price_unit",
    "size",
    "features"
  ]
}

Noteikumi starp laukiem

curl -X POST "$API/v1/boxes" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Box 2 m²",
  "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
  "price": 10,
  "promotional_price": 12,
  "total_units": 5,
  "available_units": 8,
  "price_unit": "gadsimts",
  "features": [
    "sauna"
  ]
}'

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/boxes`, {
  method: "POST",
  headers: { Authorization: auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Box 2 m²",
    "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
    "price": 10,
    "promotional_price": 12,
    "total_units": 5,
    "available_units": 8,
    "price_unit": "gadsimts",
    "features": [
      "sauna"
    ]
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/boxes",
    auth=(CLIENT_ID, CLIENT_SECRET),
    json={
        "name": "Box 2 m²",
        "location_id": "9d80d5f4-d17a-4f3e-99f6-4ab43b132bc3",
        "price": 10,
        "promotional_price": 12,
        "total_units": 5,
        "available_units": 8,
        "price_unit": "gadsimts",
        "features": [
            "sauna",
        ],
    },
)
print(r.status_code, r.json())

422 Unprocessable Content

{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "ce26822d-d546-4254-a374-08549ad6e04b",
  "errors": [
    {
      "field": "price_unit",
      "message": "is not a known price unit code"
    },
    {
      "field": "features",
      "message": "unknown or inactive feature code(s): sauna"
    },
    {
      "field": "promotional_price",
      "message": "must be lower than price"
    },
    {
      "field": "available_units",
      "message": "cannot be greater than total_units"
    }
  ]
}

#OAuth kļūdas

Token galapunkts tā vietā seko OAuth 2.0 standartam: JSON saturs ar error un error_description.

Nepareizi client piekļuves dati

curl -X POST "$API/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

const API = "https://api.boxlatvia.lv";
const auth = "Basic " + btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

const res = await fetch(`${API}/v1/oauth/token`, {
  method: "POST",
  headers: { Authorization: auth },
  body: new URLSearchParams({
    "grant_type": "client_credentials"
  }),
});
console.log(res.status, await res.json());

import requests

API = "https://api.boxlatvia.lv"
r = requests.post(
    f"{API}/v1/oauth/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "client_credentials",
    },
)
print(r.status_code, r.json())

401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Piezīme

Uztveriet 5xx un gaidīšanas laika beigas kā pagaidu problēmas: mēģiniet atkārtoti ar to pašu Idempotency-Key un pieaugošām pauzēm. Neatkārtojiet citas 4xx kļūdas, nemainot pieprasījumu (izņemot 412 pēc atkārtotas nolasīšanas un 429 pēc gaidīšanas).