Fouten en statuscodes

Bij 422 door validatie bevat het antwoord een message en per veld een lijst meldingen in errors. Velden in lijsten krijgen hun positie mee, zoals lines.0.unit_price. Validatiemeldingen zijn Engelstalig; meldingen over bedrijfsregels zijn Nederlands.

{
    "message": "The lines.0.unit_price field must be at least 0. (and 1 more error)",
    "errors": {
        "lines.0.unit_price": [
            "The lines.0.unit_price field must be at least 0."
        ],
        "customer_id": [
            "The selected customer id is invalid."
        ]
    }
}

Een verzoek dat technisch klopt maar niet mag, geeft 422 met alleen een message. Voorbeelden:

• Alleen conceptfacturen kunnen bewerkt worden.
• Alleen verzonden of verlopen offertes kunnen geaccepteerd worden.
• Deze statusovergang is niet toegestaan. (abonnementen)
• Een klant verwijderen met open documenten geeft ook blockers, bijvoorbeeld ["2 open facturen", "actieve klantenportaaltoegang"].

Zit een functie niet in het pakket, dan krijg je 403 met package_feature_unavailable. Is een limiet van het pakket bereikt (bijvoorbeeld het maximum aantal klanten), dan krijg je 422 met subscription_limit_reached.

{
    "message": "De limiet van je huidige pakket is bereikt. Upgrade je pakket om meer toe te voegen.",
    "error": {
        "code": "subscription_limit_reached",
        "feature": "customers",
        "resource": "customers",
        "current_usage": 50,
        "limit": 50,
        "upgrade_url": "https://factora.one/subscription"
    }
}

De message is bedoeld voor mensen en kan veranderen. Bouw je logica op error.code en de HTTP-status.

• Wel herhalen: 429, 500, 502, 503, 504 en netwerkfouten, met oplopende wachttijd (bijvoorbeeld 1, 2, 4, 8 seconden).
• Niet herhalen: 400–422; het verzoek moet eerst anders.
• Let op bij `POST`: na een time-out weet je niet zeker of het object is aangemaakt. Zoek het eerst op voordat je opnieuw verstuurt. Memoriaalboekingen ondersteunen idempotency_key.