Error Codes

All Priostack API errors return a JSON body with a single error field containing a human-readable message. HTTP status codes follow standard conventions.

Error Response Format

{
  "error": "insufficient credits: balance is 0, required 1"
}

Some endpoints return structured error detail for validation failures:

{
  "error": "invalid request body",
  "details": [
    { "field": "bpmnProcessId", "message": "required field missing" },
    { "field": "variables.amount", "message": "must be a number" }
  ]
}

HTTP Status Codes

Common Error Messages

Error Handling Example

// Go: handle specific error codes
resp, err := client.Do(req)
if err != nil {
    return fmt.Errorf("network error: %w", err)
}
defer resp.Body.Close()

switch resp.StatusCode {
case http.StatusOK, http.StatusCreated:
    // success
case http.StatusUnauthorized:
    return errors.New("invalid API key — check PRIOSTACK_API_KEY")
case http.StatusPaymentRequired:
    return errors.New("out of credits — free credits refresh monthly")
case http.StatusTooManyRequests:
    reset := resp.Header.Get("X-RateLimit-Reset")
    return fmt.Errorf("rate limited — retry after %s", reset)
case http.StatusInternalServerError:
    requestID := resp.Header.Get("X-Request-ID")
    return fmt.Errorf("server error (request-id: %s) — contact support", requestID)
default:
    var errBody struct{ Error string `json:"error"` }
    json.NewDecoder(resp.Body).Decode(&errBody)
    return fmt.Errorf("API error %d: %s", resp.StatusCode, errBody.Error)
}