Erros

Os erros seguem RFC 9457 (Problem Details) com Content-Type: application/problem+json.

Campos do body

type (string, URI): tipo do problema (linkável).
title (string): resumo curto do erro.
status (number): status HTTP.
detail (string, opcional): explicação mais específica.
instance (string): path da requisição.
code (string): código canônico e imutável (ex.: rate_limit_exceeded).
request_id (string): ID da requisição (também no header X-Request-Id).
errors (array, opcional): lista de erros de validação.
- field (string): caminho do campo (ex.: spec.filters.geo.uf_any_of).
- reason (string): mensagem legível.
- code (string): tipo do erro (ex.: missing).

json

{
  "type": "https://orbioapi.com.br/problems/validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "Validation error",
  "instance": "/v1/accounts/search",
  "code": "validation_error",
  "request_id": "req_01HX...",
  "errors": [
    { "field": "spec.filters.geo.uf_any_of", "reason": "Field required", "code": "missing" }
  ]
}

Códigos canônicos

Alguns dos códigos canônicos mais comuns:

authentication_required, authentication_invalid, authentication_disabled
csrf_invalid
quota_exceeded, rate_limit_exceeded
invalid_spec, query_too_broad, validation_error
cursor_mismatch, invalid_cursor, secondary_cnae_mode_not_allowed
bad_request, forbidden, not_found, conflict, gone
dependency_unavailable, service_unavailable, internal_error

Exemplos

422 — Busca ampla / validação

json

{
  "type": "https://orbioapi.com.br/problems/validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "Busca ampla demais.",
  "instance": "/v1/accounts/search",
  "code": "query_too_broad",
  "request_id": "req_01HX...",
  "errors": [
    {
      "field": "spec.filters.geo.uf_any_of",
      "reason": "UF obrigatória para este plano",
      "code": "required"
    }
  ]
}

422 — Cursor mismatch (paginação)

Quando um cursor é usado com um spec diferente (ou com defaults diferentes), a API rejeita:

json

{
  "type": "https://orbioapi.com.br/problems/validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "Cursor belongs to a different spec. Send the same spec used to obtain this cursor.",
  "instance": "/v1/accounts/search",
  "code": "cursor_mismatch",
  "request_id": "req_01HX...",
  "details": {
    "cursor_spec_fingerprint": "9f2a0c1b3d",
    "request_spec_fingerprint": "a1b2c3d4e5"
  }
}

429 — Limite de requisições

Resposta inclui Retry-After (segundos).

json

{
  "type": "https://orbioapi.com.br/problems/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "request_id": "req_01HX...",
  "code": "rate_limit_exceeded",
  "detail": "Limite de requisições excedido.",
  "instance": "/v1/accounts/search"
}

401/403 — Autenticação

json

{
  "type": "https://orbioapi.com.br/problems/authentication",
  "title": "Authentication required",
  "status": 401,
  "request_id": "req_01HX...",
  "code": "authentication_required",
  "detail": "API key ausente ou inválida.",
  "instance": "/v1/accounts/search"
}

Correções comuns

Confira Authorization: Bearer <API_KEY>.
Reduza a busca com UF + CNAE.
Respeite o limite de requisições e tente novamente com backoff.
Verifique CORS (Studio usa chamadas diretas do browser).