Errors, rate limits, and versioning

Errors

The API returns standard HTTP status codes and a machine-readable error code.

{
  "error": {
    "code": "missing_scope",
    "message": "The customer grant does not include transactions:write.",
    "requestId": "req_123"
  }
}

Status	Meaning
400	Request validation failed.
401	API key is missing, expired, or invalid.
403	The customer grant does not allow the requested action.
404	The resource is not visible to your partner application.
409	The request conflicts with current portfolio state.
429	Rate limit exceeded. Retry after the response delay.
5xx	Temporary Metrifly service error. Retry with backoff.

Rate limits

Design clients to retry 429 and read-only 5xx responses with exponential backoff and jitter. Trade writes are not idempotent in v1, so confirm whether a trade already exists in your source system or Metrifly before replaying a write after an uncertain network failure.

Versioning

The current API version is v1. Breaking changes require a new version prefix. Additive fields may appear in existing responses, so clients should ignore unknown properties.