Erros

Todos os erros são RFC 9457 Problem Details, com Content-Type: application/problem+json. Sem wrapper error: {} nem details genérico.

Cada type resolve para esta página: o slug final é a âncora da sua seção, como #not-found-404.

A forma comum

Seis campos, sempre presentes:

string

obrigatório

URI canônica e estável do tipo. É o único campo que convém comparar em código.

string

obrigatório

Texto estável por tipo. Não descreve a ocorrência.

integer

obrigatório

O mesmo código HTTP da resposta.

string

obrigatório

Descreve esta ocorrência. Não faça parse dele: não é uma interface e pode mudar sem aviso.

string

obrigatório

Alias curto em snake_case. É uma string aberta: podem aparecer códigos novos sem quebrar um cliente antigo. O slug de type é o mesmo código em kebab-case.

string

obrigatório

Identifica a ocorrência e coincide com o header X-Request-ID. É o que vai em um relatório de bug.

string

Opcional na RFC 9457, e a API não o emite.

Todo erro traz o header X-Request-ID. O 401 soma WWW-Authenticate: Bearer, e o 429, Retry-After.

O catálogo completo

`code`	Status	Slug de `type`	Extensões próprias
`invalid_request`	400	`invalid-request`	`errors[]`
`unauthorized`	401	`unauthorized`	—
`forbidden_connection`	403	`forbidden-connection`	—
`forbidden_scope`	403	`forbidden-scope`	—
`forbidden_origin`	403	`forbidden-origin`	—
`not_found`	404	`not-found`	—
`conflict`	409	`conflict`	—
`cart_items_limit_exceeded`	422	`cart-items-limit-exceeded`	`max_items_per_cart`, `actual_items`
`signal_batch_limit_exceeded`	422	`signal-batch-limit-exceeded`	`max_signals_per_batch`, `actual_signals`
`rate_limited`	429	`rate-limited`	— (header `Retry-After`)
`internal_error`	500	`internal-error`	—
`signals_unavailable`	503	`signals-unavailable`	—

As extensões vão no nível raiz do Problem, não aninhadas.

`invalid_request` — 400

O corpo ou os parâmetros não cumprem o contrato: falta um campo obrigatório, sobra um não declarado, ou um valor não valida.

{
  "type": "https://api.crossup.ai/salespilot/errors/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request body failed validation.",
  "code": "invalid_request",
  "request_id": "req_01J9ABC",
  "errors": [
    {
      "code": "missing_field",
      "detail": "context_item_id is required for surface pdp.",
      "pointer": "/context_item_id"
    }
  ]
}

array

obrigatório

Pelo menos um elemento, com code e detail obrigatórios e um pointer opcional: um JSON Pointer RFC 6901 para o campo culpado, que começa com /. Com ele você marca o input errado em vez de mostrar um texto genérico.

`unauthorized` — 401

Você não mandou Authorization, ou a chave que mandou não vale. É o mesmo erro para as duas causas: distingui-las diria a um atacante se uma chave existe.

{
  "type": "https://api.crossup.ai/salespilot/errors/unauthorized",
  "title": "Authentication required",
  "status": 401,
  "detail": "The request did not include a valid bearer token.",
  "code": "unauthorized",
  "request_id": "req_01J9ABC"
}

Ver Chaves e segurança.

`forbidden_connection` — 403

A chave autenticou bem, mas o connection_id pedido não pertence a essa loja.

{
  "type": "https://api.crossup.ai/salespilot/errors/forbidden-connection",
  "title": "Connection is not accessible",
  "status": 403,
  "detail": "The connection is not accessible to the authenticated store.",
  "code": "forbidden_connection",
  "request_id": "req_01J9ABC"
}

É 403 e não 404 porque a conexão viaja no path: o cliente já sabe que a pediu. Para recursos de catálogo é o contrário: ver not_found.

`forbidden_scope` — 403

A chave autenticou bem, mas não tem o scope da operação: recommendations:read, catalog:read ou signals:write. Uma chave não muda de scopes: é preciso outra que o tenha.

{
  "type": "https://api.crossup.ai/salespilot/errors/forbidden-scope",
  "title": "Key is missing the required scope",
  "status": 403,
  "detail": "The key does not have the signals:write scope.",
  "code": "forbidden_scope",
  "request_id": "req_01J9ABC"
}

`forbidden_origin` — 403

A chave autenticou bem e tem o scope, mas a página que a está usando não é uma das origens com as quais foi emitida. Cada chave pública (spk_) nomeia os domínios https:// de onde vale; escolhem-se ao emiti-la em API & Agentes. Um pedido sem cabeçalho Origin (um servidor, curl, Postman) e um desde http://localhost passam só com a chave: a regra é apenas para páginas https. Resolve-se emitindo uma chave que liste o domínio da loja, não mexendo no código. Uma chave sem domínios é de servidor: não serve desde nenhum storefront.

{
  "type": "https://api.crossup.ai/salespilot/errors/forbidden-origin",
  "title": "Key is not allowed from this origin",
  "status": 403,
  "detail": "The key was not issued for the origin https://otra-tienda.com. Issue a key that lists it.",
  "code": "forbidden_origin",
  "request_id": "req_01J9ABC"
}

`not_found` — 404

O recurso não existe, ou existe e é de outra loja. Nenhum detail diz qual dos dois é.

{
  "type": "https://api.crossup.ai/salespilot/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found",
  "request_id": "req_01J9ABC"
}

Um 404 inesperado com uma chave válida quase sempre é a chave de outra loja, não um id errado.

`conflict` — 409

A requisição colide com o estado atual: uma regressão de source_version na ingestão de catálogo. Um sinal mais velho que o aplicado não sobrescreve o catálogo.

{
  "type": "https://api.crossup.ai/salespilot/errors/conflict",
  "title": "Request conflicts with current state",
  "status": 409,
  "detail": "The signal source_version is older than the applied version.",
  "code": "conflict",
  "request_id": "req_01J9ABC"
}

Não repita sem mudanças: vai falhar do mesmo jeito. É um erro de ordem de eventos, não um transitório.

`cart_items_limit_exceeded` — 422

O carrinho de uma requisição de recomendações supera o limite configurado.

{
  "type": "https://api.crossup.ai/salespilot/errors/cart-items-limit-exceeded",
  "title": "Cart item limit exceeded",
  "status": 422,
  "detail": "The cart exceeds the configured item limit.",
  "code": "cart_items_limit_exceeded",
  "request_id": "req_01J9ABC",
  "max_items_per_cart": 200,
  "actual_items": 512
}

integer

obrigatório

O limite vigente, 200 por padrão. Vem na resposta para que você não o fixe no código.

integer

obrigatório

Quantos itens você mandou.

`signal_batch_limit_exceeded` — 422

Um lote de sinais do storefront traz mais do que o permitido.

{
  "type": "https://api.crossup.ai/salespilot/errors/signal-batch-limit-exceeded",
  "title": "Signal batch limit exceeded",
  "status": 422,
  "detail": "The batch exceeds the signal limit.",
  "code": "signal_batch_limit_exceeded",
  "request_id": "req_01J9ABC",
  "max_signals_per_batch": 50,
  "actual_signals": 80
}

integer

obrigatório

O limite vigente, 50 por padrão. O SDK já divide os lotes com este número.

integer

obrigatório

Quantos sinais você mandou.

`rate_limited` — 429

A chave gastou suas 60 requisições por minuto; Retry-After diz quantos segundos esperar. Ver Cota e cache.

{
  "type": "https://api.crossup.ai/salespilot/errors/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "The key exceeded its request budget.",
  "code": "rate_limited",
  "request_id": "req_01J9ABC"
}

`internal_error` — 500

Algo quebrou do lado do servidor. O detail nunca traz o stack, a mensagem interna nem o nome de um componente.

{
  "type": "https://api.crossup.ai/salespilot/errors/internal-error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected internal error occurred.",
  "code": "internal_error",
  "request_id": "req_01J9ABC"
}

Aqui o request_id é imprescindível: conecta o que você viu com o log do servidor.

`signals_unavailable` — 503

O armazenamento de sinais do storefront não está disponível. É transitório: tente de novo com espera. O SDK faz isso sozinho, com o mesmo signal_id, e uma nova tentativa nunca conta duas vezes.

{
  "type": "https://api.crossup.ai/salespilot/errors/signals-unavailable",
  "title": "Signals cannot be recorded right now",
  "status": 503,
  "detail": "The signal store is unavailable.",
  "code": "signals_unavailable",
  "request_id": "req_01J9ABC"
}

Como tratá-los a partir do SDK

O SDK traduz qualquer um destes Problems para um CrossUpApiError tipado e preserva as extensões que não conhece, para não quebrar quando a API somar campos.

import { isCrossUpApiError } from "@crossup/storefront";

try {
  await crossup.getCatalogItem("itm_demo_remera");
} catch (err) {
  if (isCrossUpApiError(err) && err.is("unauthorized", "forbidden_scope")) {
    console.log("revise a chave ·", err.requestId);
  }
  throw err;
}

Use isCrossUpApiError(err) e não err instanceof CrossUpApiError: instanceof falha se há duas cópias do pacote na árvore de módulos.

Três regras do SDK para quando algo dá errado de verdade:

Não se olha o Content-Type, olha-se a forma do corpo. Um proxy pode reescrever o header, e o erro é tipado mesmo assim.
O status do transporte manda. Se o corpo declara outro, a diferença fica em extensions.status: é a prova de que algo no meio reescreve respostas.
errorFromResponse nunca lança. Diante de HTML, corpo vazio ou JSON que não é um Problem, devolve um erro sintético com code: "unexpected_response", o status real e o corpo cru.

​A forma comum

​O catálogo completo

​invalid_request — 400

​unauthorized — 401

​forbidden_connection — 403

​forbidden_scope — 403

​forbidden_origin — 403

​not_found — 404

​conflict — 409

​cart_items_limit_exceeded — 422

​signal_batch_limit_exceeded — 422

​rate_limited — 429

​internal_error — 500

​signals_unavailable — 503

​Como tratá-los a partir do SDK

A forma comum

O catálogo completo

`invalid_request` — 400

`unauthorized` — 401

`forbidden_connection` — 403

`forbidden_scope` — 403

`forbidden_origin` — 403

`not_found` — 404

`conflict` — 409

`cart_items_limit_exceeded` — 422

`signal_batch_limit_exceeded` — 422

`rate_limited` — 429

`internal_error` — 500

`signals_unavailable` — 503

Como tratá-los a partir do SDK