Errors API

Report errors to MiniAPM for tracking, grouping, and analysis.

Single Error

Endpoint

POST /ingest/errors

Headers

Header	Required	Description
Authorization	Yes	Bearer <api_key>
Content-Type	Yes	application/json

Request Body

{
  "error_type": "RuntimeError",
  "message": "Something went wrong",
  "backtrace": [
    "app/models/user.rb:42:in `save`",
    "app/controllers/users_controller.rb:15:in `create`"
  ],
  "context": {
    "user_id": 123,
    "request_id": "abc-123-def"
  },
  "environment": "production",
  "git_sha": "abc123def",
  "happened_at": "2024-01-01T12:00:00Z"
}

Fields

Field	Type	Required	Description
error_type	string	Yes	Exception class name
message	string	Yes	Error message
backtrace	array	No	Stack trace lines
context	object	No	Additional context data
environment	string	No	Environment name
git_sha	string	No	Git commit SHA
happened_at	string	No	ISO 8601 timestamp
user_id	string	No	User identifier
request_id	string	No	Request identifier
trace_id	string	No	Trace ID for linking
span_id	string	No	Span ID for linking

Response

{
  "id": "err_abc123",
  "fingerprint": "a1b2c3d4e5f6"
}

Example

curl -X POST http://localhost:3000/ingest/errors \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "error_type": "ActiveRecord::RecordNotFound",
    "message": "Could not find User with id=999",
    "backtrace": [
      "app/controllers/users_controller.rb:10:in `show`",
      "lib/middleware/auth.rb:25:in `call`"
    ],
    "context": {
      "user_id": 123,
      "params": { "id": "999" }
    },
    "environment": "production"
  }'

Batch Errors

Report multiple errors in a single request.

Endpoint

POST /ingest/errors/batch

Request Body

{
  "errors": [
    {
      "error_type": "RuntimeError",
      "message": "Error 1",
      "backtrace": ["..."]
    },
    {
      "error_type": "NoMethodError",
      "message": "Error 2",
      "backtrace": ["..."]
    }
  ]
}

Response

{
  "accepted": 2,
  "errors": []
}

Error Grouping

MiniAPM automatically groups errors by fingerprint, which is computed from:

1. Error type (class name)
2. Error message (normalized)
3. Top stack frame location

Errors with the same fingerprint are grouped together, showing:

• First seen timestamp
• Last seen timestamp
• Occurrence count
• Trend over time

Source Context

If you include file paths in your backtrace, MiniAPM can display source context (lines before/after the error). Send structured backtrace entries:

{
  "backtrace": [
    {
      "file": "app/models/user.rb",
      "line": 42,
      "method": "save",
      "pre_context": ["  def save", "    validate!"],
      "context_line": "    raise 'Invalid' unless valid?",
      "post_context": ["  end", ""]
    }
  ]
}

Error Status

Errors can be managed through the web UI:

• Open - New or active error
• Resolved - Fixed, but can reopen if it recurs
• Ignored - Won’t show in dashboard

Integration Examples

Ruby (manual)

begin
  risky_operation
rescue => e
  MiniAPM.record_error(e, context: {
    user_id: current_user.id,
    params: request.params.except(:password)
  })
  raise
end

Ruby (automatic)

The miniapm gem captures exceptions automatically in Rails.

Python

import requests

def report_error(exception, context=None):
    import traceback

    requests.post(
        'http://localhost:3000/ingest/errors',
        headers={
            'Authorization': 'Bearer proj_abc123...',
            'Content-Type': 'application/json'
        },
        json={
            'error_type': type(exception).__name__,
            'message': str(exception),
            'backtrace': traceback.format_exception(exception),
            'context': context or {}
        }
    )

JavaScript

async function reportError(error, context = {}) {
  await fetch('http://localhost:3000/ingest/errors', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer proj_abc123...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      error_type: error.name,
      message: error.message,
      backtrace: error.stack?.split('\n') || [],
      context
    })
  });
}