Formato de resposta e erros

O envelope

Toda resposta JSON da API vem no mesmo envelope, com sucesso ou erro. O campo statusCode repete o status HTTP, para quem lê só o corpo.

{
  "success": true,
  "statusCode": 200,
  "data": { "id": "ckx3lead0000ab7d3k1e5xyz", "name": "Carlos Lima" }
}

Erros

{
  "success": false,
  "statusCode": 422,
  "message": "Dados inválidos",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "code": "too_small",
        "path": ["name"],
        "message": "Nome é obrigatório"
      }
    ]
  }
}

• Trate pelo error.code, nunca pela message. O código é contrato; a mensagem é texto para pessoas e pode mudar.
• VALIDATION_ERROR traz em details a lista de problemas do corpo ou da query: path diz o campo, message o que está errado. JSON malformado também é VALIDATION_ERROR, com a mensagem Corpo inválido (JSON malformado).
• RATE_LIMITED traz details.retryAfterSeconds e o header Retry-After. Veja Limites de requisição.
• Erros 5xx são do lado do Steel ou de um serviço externo (e-mail, Meta, GitHub). Pode tentar de novo com espera crescente.

Um tratador de erros completo

async function callSteel(path, init = {}) {
  const response = await fetch(`${process.env.STEEL_URL}/api${path}`, init)
  const body = await response.json()
  if (body.success) return body.data

  const error = new Error(body.message ?? body.error.code)
  error.status = body.statusCode
  error.code = body.error.code
  error.details = body.error.details
  error.retryAfter = Number(response.headers.get('Retry-After')) || null
  throw error
}

try {
  const lead = await callSteel('/crm/integrations/leads', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.STEEL_CRM_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Carlos Lima', emails: ['carlos@empresa.com.br'] }),
  })
  console.log(lead.id)
} catch (error) {
  if (error.code === 'VALIDATION_ERROR') console.error(error.details)
  else if (error.code === 'RATE_LIMITED') console.warn(`Tente em ${error.retryAfter}s`)
  else throw error
}