Error Codes

Engine and account routes answer an error with an application/json body holding a single error field: a human-readable message. There is no machine-readable error code, so branch on the HTTP status, not on the text. Two answers are not JSON: the firewall's 429 is text/plain "Too Many Requests", and an IP it has banned gets 403 with an empty body.

Error Response Format

{
  "error": "process \"order-processing\" not deployed"
}

One route adds two fields. When POST /api/v1/process-instances cannot take its credit, the 402 body is:

{
  "error": "insufficient credits: have 0, need 1",
  "balance": 0,
  "buy": "https://priostack.com/credits"
}

balance is currently always 0, whatever the real balance (read GET /api/credits for it), and packs are bought at priostack.com/wallet. The same error field can also read account is disabled, or unknown api key for a key with no account. Every other charged route answers {"error":"insufficient credits"}.

HTTP Status Codes

Common Error Messages

Error Handling Example

package priostack

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

// checkResponse turns a Priostack response into an error. Success is any 2xx:
// job activation answers 200, instance start 201, job complete and fail 204.
func checkResponse(resp *http.Response) error {
    if resp.StatusCode/100 == 2 {
        return nil
    }
    body, _ := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
    msg := string(body) // 429 is plain text and a banned IP's 403 is empty
    var e struct {
        Error string `json:"error"`
    }
    if json.Unmarshal(body, &e) == nil && e.Error != "" {
        msg = e.Error
    }
    switch resp.StatusCode {
    case http.StatusUnauthorized:
        return fmt.Errorf("invalid or missing API key: %s", msg)
    case http.StatusPaymentRequired:
        return fmt.Errorf("out of credits (%s): buy a pack at https://priostack.com/wallet or wait for the daily grant", msg)
    case http.StatusTooManyRequests:
        return fmt.Errorf("rate limited: wait about 60 seconds before retrying")
    case http.StatusForbidden:
        return fmt.Errorf("forbidden %q (an empty body means the firewall banned this IP)", msg)
    default:
        return fmt.Errorf("API error %d: %s (request id %s)", resp.StatusCode, msg, resp.Header.Get("X-Request-ID"))
    }
}