# Conventions, as measured

Status: Live
Updated: 2026-09-30
Verified against: ecosystem cecd4003

These conventions describe what Paintaire does today, not a target. The shared marketplace layer is consistent; contractor deployments are separate systems that follow the patterns below only loosely, so check the contract of the service you are calling. For the marketplace routes, see the [Agent API](https://paintaire.com/developers/agent-api) and the [lead and newsletter contracts](https://paintaire.com/developers/leads).

## Authentication

Marketplace agent routes use `Authorization: Bearer <token>`. Each token carries scopes, and an action needs its scope. Credentials are issued by Paintaire on request.

Contractor deployments follow a different pattern: each service has its own API keys, issued by that deployment's owner. The header is usually `X-API-Key`, and some services use `Authorization: Bearer` instead. The header is specific to the service, and sending the wrong one gets a bare `401` with no hint about which header was expected. Do not reuse a credential across services.

Verified against ecosystem `cecd4003`

## Errors

Marketplace routes return a flat `{ "error": "<message>" }`, and some add fields that help you react: `retry_after` on a `429`, `retryable` when an execution is already in progress, `fields` listing missing form fields, and `confirmation_required` with `confirmation_statement` when an action still needs explicit confirmation. Other Paintaire services use one of several envelope shapes. The direction of travel is a single envelope, `{ "error": { "code", "message", "details", "request_id" } }`, but do not assume it yet. Parse by HTTP status first, then read whatever body is present defensively, and log `request_id` when a service supplies one.

Verified against ecosystem `cecd4003`

## Rate limits

There is no platform-wide limiter. Limits, and the headers that report them, are set per service, so read the contract of each service you call. Honor `Retry-After` when present; some services send a `429` without it, so back off on your own. The marketplace routes send it in seconds. Do not build on `X-RateLimit-Reset`: its units are not consistent across services.

Verified against ecosystem `cecd4003`

## Data

Money does not appear on the marketplace routes. Across Paintaire services the platform convention is that money crosses service boundaries as integer cents unless the owning service's contract says otherwise, and at least one service is an exception that stores dollars. Check the contract before doing arithmetic on an amount.

Timestamps on the marketplace routes, including action previews and receipts, are ISO-8601 in UTC. Contractor services vary, so read their contracts.

The Agent API's execute route requires an `Idempotency-Key` header, so a retry after a timeout replays the same receipt instead of creating a duplicate. The other marketplace routes do not take one.

Verified against this site's code and the platform conventions in ecosystem `cecd4003`

Human page: https://paintaire.com/developers/conventions