Docs/API reference

Errors

The error body every endpoint returns, and how to handle failures in your own uploader.

Every error response has the same shape: an object with an error key holding a machine-readable code and a human-readable message.

json

{
  "error": {
    "code": "invalid_request",
    "message": "period must be YYYY-MM"
  }
}

Field	Type	Meaning
`error.code`	string	A stable identifier for the kind of error. Branch on this.
`error.message`	string	A description for people. It may change, so do not parse it.

Handling errors

Check the HTTP status first, then error.code.
Do not retry a request that failed because of bad input or a bad key. Fix the cause first.
POST /api/v1/sources is idempotent on the source name, so it is safe to call again after a network failure.
If an upload to the upload URL fails, the batch stays in awaiting_upload. Create a new batch and upload again.