Error Handling

The Baanko API returns errors following the RFC 7807 standard (Problem Details for HTTP APIs). Text fields such as detail and message are returned in Portuguese, so match on the HTTP status and field names, not on the message text.

Error Format

Error Example

{
  "type": "https://baanko.app/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Os dados fornecidos sao invalidos.",
  "instance": "/api/v1/transactions/create",
  "errors": [
    {
      "field": "amount",
      "message": "O valor deve ser maior que zero."
    }
  ],
  "traceId": "00-abc123-def456-00"
}

HTTP Status Codes

400

Bad Request

Invalid request. Check the parameters you sent.

401

Unauthorized

Missing or invalid credentials.

403

Forbidden

Access to the resource was denied.

404

Not Found

Resource not found.

429

Too Many Requests

Rate limit exceeded.

500

Internal Server Error

Internal server error.

Best Practices

Always check the response status before processing the data.

Include the traceId field when reporting problems to support.

Retry with exponential backoff on 429 and 5xx errors.

Validate data on your side before sending it to the API.

Handling Example

JavaScript

const response = await fetch('https://baanko.app/api/v1/transactions/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Id': CLIENT_ID,
    'X-API-Key': API_KEY
  },
  body: JSON.stringify(data)
});
const result = await response.json();
if (!response.ok) {
  console.error('Error:', result.title);
  console.error('Details:', result.detail);
  console.error('TraceId:', result.traceId);
  
  if (result.errors) {
    result.errors.forEach(err => {
      console.error(`Field ${err.field}: ${err.message}`);
    });
  }
  return;
}
console.log('Success:', result.data);